Adapters

Since version 2, you can now use nuqs in the following React frameworks, by wrapping it with a NuqsAdapter context provider:

Next.js (app router)
Next.js (pages router)
React SPA (eg: with Vite)
Remix
React Router

Next.js

App router

Wrap your {children} with the NuqsAdapter component in your root layout file:

src/app/layout.tsx

import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { type ReactNode } from 'react'
 
export default function RootLayout({
  children
}: {
  children: ReactNode
}) {
  return (
    <html>
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  )
}

Pages router

Wrap the <Component> page outlet with the NuqsAdapter component in your _app.tsx file:

src/pages/_app.tsx

import type { AppProps } from 'next/app'
import { NuqsAdapter } from 'nuqs/adapters/next/pages'
 
export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <NuqsAdapter>
      <Component {...pageProps} />
    </NuqsAdapter>
  )
}

Unified (router-agnostic)

If your Next.js app uses both the app and pages routers and the adapter needs to be mounted in either, you can import the unified adapter, at the cost of a slightly larger bundle size (~100B).

import { NuqsAdapter } from 'nuqs/adapters/next'

The main reason for adapters is to open up nuqs to other React frameworks:

React SPA

Example, with Vite:

src/main.tsx

import { NuqsAdapter } from 'nuqs/adapters/react'
 
createRoot(document.getElementById('root')!).render(
  <NuqsAdapter>
    <App />
  </NuqsAdapter>
)

Remix

app/root.tsx

import { NuqsAdapter } from 'nuqs/adapters/remix'
 
// ...
 
export default function App() {
  return (
    <NuqsAdapter>
      <Outlet />
    </NuqsAdapter>
  )
}

React Router

src/main.tsx

import { NuqsAdapter } from 'nuqs/adapters/react-router'
import { createBrowserRouter, RouterProvider } from 'react-router-dom'
import App from './App'
 
const router = createBrowserRouter([
  {
    path: '/',
    element: <App />
  }
])
 
export function ReactRouter() {
  return (
    <NuqsAdapter>
      <RouterProvider router={router} />
    </NuqsAdapter>
  )
}

Testing

Documentation for the NuqsTestingAdapter is on the testing page.

On this page