NuqsTestingAdapter

API reference for the NuqsTestingAdapter component and testing utilities

The NuqsTestingAdapter provides a test environment for components that use nuqs hooks. It simulates URL state management without requiring a real router, making it easy to test components in isolation.

NuqsTestingAdapter

A React component that provides a testing context for nuqs hooks.

Props

searchParams · string | Record<string, string> | URLSearchParams

Initial search params for the test. Can be provided as:

• A query string: "?foo=bar&baz=qux"
• A record object: { foo: "bar", baz: "qux" }
• A URLSearchParams instance: new URLSearchParams("foo=bar")

Defaults to an empty string (no search params).

onUrlUpdate · OnUrlUpdateFunction

A callback function invoked whenever the URL is updated. Useful for asserting URL changes in tests.

The function receives a UrlUpdateEvent object containing:

• searchParams: The new search params as a URLSearchParams instance
• queryString: The rendered query string
• options: The options used for the URL update

const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()

render(<Component />, {
  wrapper: withNuqsTestingAdapter({ onUrlUpdate })
})

// Later in your test
expect(onUrlUpdate).toHaveBeenCalledWith({
  searchParams: expect.any(URLSearchParams),
  queryString: '?foo=bar',
  options: expect.objectContaining({
    history: 'push'
  })
})

hasMemory · boolean · default: "false"

Controls whether the adapter stores search params in memory and updates them on each URL change.

• false (default): The adapter is immutable. Search params remain frozen to the initial value. This encourages testing discrete units of behavior.
• true: The adapter behaves like framework adapters, storing updates in memory so subsequent updates build on the previous state.

// Immutable (default) - always starts from initial state
withNuqsTestingAdapter({ searchParams: '?count=0' })

// Stateful - updates accumulate
withNuqsTestingAdapter({ searchParams: '?count=0', hasMemory: true })

autoResetQueueOnUpdate · boolean · default: "true"

Whether to automatically reset the URL update queue after each update.

In production, nuqs batches and throttles URL updates. This option controls whether the queue should be cleared after processing updates during tests.

resetUrlUpdateQueueOnMount · boolean · default: "true"

Whether to clear the URL update queue when the adapter mounts.

Since the update queue is a shared global, this option ensures test isolation by clearing the queue before each test. Set to false to preserve the queue between renders for testing edge cases.

rateLimitFactor · number · default: "0"

Controls throttling behavior during tests.

• 0 (default): No throttling - updates are immediate
• 1: Production throttling (≥50ms)
• Other values: Custom throttling factor

Most tests should use the default to avoid timing-related flakiness.

defaultOptions · object

Default options to apply to all useQueryState hooks within this adapter.

withNuqsTestingAdapter({
  defaultOptions: {
    shallow: false,
    scroll: true,
    clearOnDefault: true,
    limitUrlUpdates: false
  }
})

Supported options:

• shallow: Whether to use shallow routing (framework-specific)
• scroll: Whether to scroll to top on URL updates
• clearOnDefault: Whether to remove the key from URL when set to default value
• limitUrlUpdates: Whether to limit the rate of URL updates

processUrlSearchParams · (search: URLSearchParams) => URLSearchParams

A function to process or transform search params before they’re used by hooks.

withNuqsTestingAdapter({
  processUrlSearchParams: (search) => {
    // Example: add authentication token to all requests
    search.set('token', 'test-token')
    return search
  }
})

children · ReactNode · required

The components to render within the testing adapter context.

withNuqsTestingAdapter

A higher-order component that creates a wrapper function for testing libraries that support wrapper components (e.g., Testing Library, Vitest).

Signature

function withNuqsTestingAdapter(
  props?: Omit<TestingAdapterProps, 'children'>
): ({ children }: { children: ReactNode }) => ReactElement

Parameters

Accepts all NuqsTestingAdapter props except children.

Returns

A wrapper component function that can be passed to testing library render methods.

Usage

import { withNuqsTestingAdapter } from 'nuqs/adapters/testing'
import { renderHook } from '@testing-library/react'

const { result } = renderHook(() => useQueryState('foo'), {
  wrapper: withNuqsTestingAdapter({
    searchParams: '?foo=bar'
  })
})

Types

UrlUpdateEvent

The event object passed to the onUrlUpdate callback.

type UrlUpdateEvent = {
  searchParams: URLSearchParams
  queryString: string
  options: Required<AdapterOptions>
}

searchParams · URLSearchParams

The new search params as a URLSearchParams instance. This is a copy that can be safely inspected or modified.

queryString · string

The rendered query string representation of the search params (e.g., "?foo=bar&baz=qux").

options · Required<AdapterOptions>

The options used for the URL update:

• history: "push" | "replace" - The history method used
• scroll: boolean - Whether to scroll to top
• shallow: boolean - Whether shallow routing was used

OnUrlUpdateFunction

The type signature for the onUrlUpdate callback function.

type OnUrlUpdateFunction = (event: UrlUpdateEvent) => void

Complete Example

Here’s a complete example testing a counter component:

counter.test.tsx

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { describe, expect, it, vi } from 'vitest'
import { 
  withNuqsTestingAdapter, 
  type OnUrlUpdateFunction 
} from 'nuqs/adapters/testing'
import { Counter } from './counter'

describe('Counter', () => {
  it('should increment count and update URL', async () => {
    const user = userEvent.setup()
    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
    
    // 1. Setup: Render with initial search params
    render(<Counter />, {
      wrapper: withNuqsTestingAdapter({ 
        searchParams: '?count=5',
        onUrlUpdate 
      })
    })
    
    // 2. Act: Click the increment button
    const button = screen.getByRole('button', { name: /increment/i })
    await user.click(button)
    
    // 3. Assert: Check state and URL updates
    expect(button).toHaveTextContent('6')
    expect(onUrlUpdate).toHaveBeenCalledOnce()
    
    const event = onUrlUpdate.mock.calls[0][0]
    expect(event.queryString).toBe('?count=6')
    expect(event.searchParams.get('count')).toBe('6')
    expect(event.options.history).toBe('push')
  })
  
  it('should handle multiple updates with hasMemory', async () => {
    const user = userEvent.setup()
    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
    
    render(<Counter />, {
      wrapper: withNuqsTestingAdapter({ 
        searchParams: '?count=0',
        hasMemory: true,
        onUrlUpdate 
      })
    })
    
    const button = screen.getByRole('button', { name: /increment/i })
    
    // First click
    await user.click(button)
    expect(onUrlUpdate).toHaveBeenCalledTimes(1)
    expect(onUrlUpdate.mock.calls[0][0].queryString).toBe('?count=1')
    
    // Second click - with hasMemory, it builds on previous state
    await user.click(button)
    expect(onUrlUpdate).toHaveBeenCalledTimes(2)
    expect(onUrlUpdate.mock.calls[1][0].queryString).toBe('?count=2')
  })
  
  it('should work with object syntax for searchParams', () => {
    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>()
    
    render(<Counter />, {
      wrapper: withNuqsTestingAdapter({ 
        searchParams: { count: '10', page: '1' },
        onUrlUpdate 
      })
    })
    
    expect(screen.getByRole('button')).toHaveTextContent('10')
  })
})

Direct Component Usage

You can also use NuqsTestingAdapter directly as a component:

import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
import { render } from '@testing-library/react'

it('should render with initial params', () => {
  const onUrlUpdate = vi.fn()
  
  render(
    <NuqsTestingAdapter 
      searchParams="?search=hello&limit=10"
      onUrlUpdate={onUrlUpdate}
    >
      <MySearchComponent />
    </NuqsTestingAdapter>
  )
  
  // Your assertions here
})

See Also

• Testing Guide - Complete guide to testing with nuqs
• Custom Adapters - Creating custom adapters for other frameworks