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>
)

Note: because there is no known server in this configuration, the shallow: false option will have no effect.

Since nuqs@2.4.0, you can specify a flag to perform a full-page navigation when updating query state configured with shallow: false, to notify the web server that the URL state has changed, if it needs it for server-side rendering other parts of the application than the static React bundle:

src/main.tsx

createRoot(document.getElementById('root')!).render(
  <NuqsAdapter fullPageNavigationOnShallowFalseUpdates>
    <App />
  </NuqsAdapter>
)

This may be useful for servers not written in JavaScript, like Django (Python), Rails (Ruby), Laravel (PHP), Phoenix (Elixir) etc…

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>
  )
}

Only BrowserRouter is supported. There may be support for HashRouter in the future (see issue #810), but support for MemoryRouter is not planned.

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.

The main difference is where the React Router hooks are imported from: react-router-dom for v6, and react-router for v7.

Testing

Documentation for the NuqsTestingAdapter is on the testing page.

On this page