> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/47ng/nuqs/llms.txt > Use this file to discover all available pages before exploring further. # Next.js App Router Adapter > Setup and configure nuqs for Next.js App Router applications The Next.js App Router adapter enables nuqs to work seamlessly with Next.js 14.2.0 and above using the App Router. ## Installation First, install nuqs in your Next.js project: ```bash theme={null} npm install nuqs ``` ```bash theme={null} pnpm add nuqs ``` ```bash theme={null} yarn add nuqs ``` Wrap your application with the `NuqsAdapter` in your root layout file: ```tsx title="app/layout.tsx" theme={null} import { NuqsAdapter } from 'nuqs/adapters/next/app' import type { ReactNode } from 'react' export default function RootLayout({ children }: { children: ReactNode }) { return ( {children} ) } ``` The adapter must be placed inside the `` tag and wrap all content that uses nuqs hooks. Now you can use `useQueryState` and `useQueryStates` in any client component: ```tsx title="app/search.tsx" theme={null} 'use client' import { useQueryState } from 'nuqs' export default function SearchComponent() { const [search, setSearch] = useQueryState('q') return (
setSearch(e.target.value)} placeholder="Search..." />

Search query: {search || 'none'}

) } ``` ## 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: ```tsx theme={null} const [state, setState] = useQueryState('key') // Updates only happen on the client ``` ### Server Re-renders Opt into server-side rendering updates by setting `shallow: false`: ```tsx theme={null} 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: ```tsx theme={null} '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 (
setQuery(e.target.value)} disabled={isLoading} /> {isLoading && Loading...}
) } ``` ## How It Works The Next.js App Router adapter: 1. Uses `useSearchParams()` from `next/navigation` to read the current URL state 2. Uses `useOptimistic()` to provide instant UI updates 3. Calls `router.replace()` for non-shallow updates to trigger server re-renders 4. Patches the History API to detect navigation events and reset internal queues 5. Batches multiple state updates efficiently ## Server Components For accessing search params in Server Components, use `createSearchParamsCache`: ```tsx title="app/page.tsx" theme={null} import { createSearchParamsCache, parseAsString } from 'nuqs/server' export const searchParamsCache = createSearchParamsCache({ q: parseAsString.withDefault('') }) export default async function Page({ searchParams }: { searchParams: Promise> }) { const { q } = await searchParamsCache.parse(searchParams) return
Search: {q}
} ``` See the [Server-Side Parsing](/server/overview) documentation for more details. ## Troubleshooting ### Adapter must be inside `` The adapter relies on browser APIs and must be rendered inside the `` tag. Placing it in `` or outside `` 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: 1. The component using nuqs hooks has the `'use client'` directive 2. The component is a child of the `NuqsAdapter` 3. You're not accidentally using the wrong adapter (e.g., pages router adapter)