Next.js App Router Adapter

The Next.js App Router adapter enables nuqs to work seamlessly with Next.js 14.2.0 and above using the App Router.

Installation

Install nuqs

First, install nuqs in your Next.js project:

npm install nuqs

pnpm add nuqs

yarn add nuqs

Add the adapter to your root layout

Wrap your application with the NuqsAdapter in your root layout file:

app/layout.tsx

import { NuqsAdapter } from 'nuqs/adapters/next/app'
import type { ReactNode } from 'react'

export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
  <body>
    <NuqsAdapter>{children}</NuqsAdapter>
  </body>
</html>
)
}

The adapter must be placed inside the <body> tag and wrap all content that uses nuqs hooks.

Use nuqs hooks in your client components

Now you can use useQueryState and useQueryStates in any client component:

app/search.tsx

'use client'

import { useQueryState } from 'nuqs'

export default function SearchComponent() {
const [search, setSearch] = useQueryState('q')

return (
<div>
  <input
    value={search || ''}
    onChange={(e) => setSearch(e.target.value)}
    placeholder="Search..."
  />
  <p>Search query: {search || 'none'}</p>
</div>
)
}

Version Requirements

Next.js: >=14.2.0
React: >=18.2.0 or ^19.0.0-0

For Next.js versions older than 14.2.0, use nuqs v1.x instead, which doesn’t require the adapter setup.

Features

Shallow Updates (Default)

By default, URL updates are client-side only and don’t trigger server re-renders:

const [state, setState] = useQueryState('key')
// Updates only happen on the client

Server Re-renders

Opt into server-side rendering updates by setting shallow: false:

const [state, setState] = useQueryState('key', { shallow: false })
// URL updates will trigger server component re-renders

Transitions

Combine with React’s useTransition for loading states during server updates:

'use client'

import { useTransition } from 'react'
import { useQueryState, parseAsString } from 'nuqs'

export function SearchWithLoading() {
  const [isLoading, startTransition] = useTransition()
  const [query, setQuery] = useQueryState(
    'q',
    parseAsString.withOptions({
      shallow: false,
      startTransition
    })
  )

  return (
    <div>
      <input
        value={query || ''}
        onChange={(e) => setQuery(e.target.value)}
        disabled={isLoading}
      />
      {isLoading && <span>Loading...</span>}
    </div>
  )
}

How It Works

The Next.js App Router adapter:

Uses useSearchParams() from next/navigation to read the current URL state
Uses useOptimistic() to provide instant UI updates
Calls router.replace() for non-shallow updates to trigger server re-renders
Patches the History API to detect navigation events and reset internal queues
Batches multiple state updates efficiently

Server Components

For accessing search params in Server Components, use createSearchParamsCache:

app/page.tsx

import { createSearchParamsCache, parseAsString } from 'nuqs/server'

export const searchParamsCache = createSearchParamsCache({
  q: parseAsString.withDefault('')
})

export default async function Page({
  searchParams
}: {
  searchParams: Promise<Record<string, string | string[] | undefined>>
}) {
  const { q } = await searchParamsCache.parse(searchParams)
  return <div>Search: {q}</div>
}

See the Server-Side Parsing documentation for more details.

Troubleshooting

Adapter must be inside `<body>`

The adapter relies on browser APIs and must be rendered inside the <body> tag. Placing it in <head> or outside <html> will cause errors.

Not working with Next.js 14.1 or older

The App Router adapter requires Next.js 14.2.0 or newer. For older versions:

Upgrade to Next.js 14.2.0+, or
Use nuqs v1.x which has built-in support for older Next.js versions

Search params not updating

Make sure:

The component using nuqs hooks has the 'use client' directive
The component is a child of the NuqsAdapter
You’re not accidentally using the wrong adapter (e.g., pages router adapter)

Getting Started

Core Concepts

Framework Adapters

Server-Side

Advanced

Migration

Next.js App Router Adapter

Installation

Version Requirements

Features

Shallow Updates (Default)

Server Re-renders

Transitions

How It Works

Server Components

Troubleshooting

Adapter must be inside `<body>`

Not working with Next.js 14.1 or older

Search params not updating

​Installation

​Version Requirements

​Features

​Shallow Updates (Default)

​Server Re-renders

​Transitions

​How It Works

​Server Components

​Troubleshooting

​Adapter must be inside <body>

​Not working with Next.js 14.1 or older

​Search params not updating

Installation

Version Requirements

Features

Shallow Updates (Default)

Server Re-renders

Transitions

How It Works

Server Components

Troubleshooting

Adapter must be inside `<body>`

Not working with Next.js 14.1 or older

Search params not updating