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 v6
React Router v7

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 v6

src/main.tsx


import { NuqsAdapter } from 'nuqs/adapters/react-router/v6'
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>
  )
}

React Router v7

app/root.tsx


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

Deprecation notice

The generic import nuqs/adapters/react-router (pointing to v6) is deprecated and will be removed in nuqs@3.0.0.

Please pin your imports to the specific version, eg: nuqs/adapters/react-router/v6 or nuqs/adapters/react-router/v7.

Testing

Documentation for the NuqsTestingAdapter is on the testing page.

On this page