Adapters
Using nuqs in your React framework of choice
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:
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:
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:
import { NuqsAdapter } from 'nuqs/adapters/react'
createRoot(document.getElementById('root')!).render(
<NuqsAdapter>
<App />
</NuqsAdapter>
)
Remix
import { NuqsAdapter } from 'nuqs/adapters/remix'
// ...
export default function App() {
return (
<NuqsAdapter>
<Outlet />
</NuqsAdapter>
)
}
React Router v6
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
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.