Install the Package
Install nuqs using your preferred package manager:
nuqs requires React 18.2.0 or higher. For Next.js, version 14.2.0+ is required.
Set Up Your Adapter
nuqs requires a framework adapter to be wrapped around your React component tree. Choose the adapter that matches your framework:
Next.js (App Router)
Recommended for Next.js 14.2.0 and above with the app directory.
NuqsAdapter in your root layout:
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>
)
}
Next.js (Pages Router)
Wrap your application in _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>
)
}
React (SPA)
For plain React applications (Vite, Create React App, etc.):
import { createRoot } from 'react-dom/client'
import { NuqsAdapter } from 'nuqs/adapters/react'
import App from './App'
createRoot(document.getElementById('root')!).render(
<NuqsAdapter>
<App />
</NuqsAdapter>
)
Remix
Requires @remix-run/react version 2 or higher.
import { NuqsAdapter } from 'nuqs/adapters/remix'
import { Outlet } from '@remix-run/react'
export default function App() {
return (
<NuqsAdapter>
<Outlet />
</NuqsAdapter>
)
}
React Router v6
Requires react-router-dom version 6.
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 Root() {
return (
<NuqsAdapter>
<RouterProvider router={router} />
</NuqsAdapter>
)
}
React Router v7
Wrap your application in the root route:
import { NuqsAdapter } from 'nuqs/adapters/react-router/v7'
import { Outlet } from 'react-router'
export default function App() {
return (
<NuqsAdapter>
<Outlet />
</NuqsAdapter>
)
}
TanStack Router
TanStack Router support is experimental and does not yet cover TanStack Start.
import { NuqsAdapter } from 'nuqs/adapters/tanstack-router'
import { Outlet, createRootRoute } from '@tanstack/react-router'
export const Route = createRootRoute({
component: () => (
<NuqsAdapter>
<Outlet />
</NuqsAdapter>
)
})
Custom Adapter
If you’re using a different router or framework, you can create a custom adapter. See the Custom Adapter guide for details.
Verify Installation
You’re all set! Let’s verify everything works by creating a simple component:
Only needed for Next.js App Router
import { useQueryState } from 'nuqs'
export default function TestComponent() {
const [test, setTest] = useQueryState('test')
return (
<div>
<p>Value: {test || 'none'}</p>
<button onClick={() => setTest('hello')}>Set Test</button>
<button onClick={() => setTest(null)}>Clear</button>
</div>
)
}
?test=hello!
Next Steps
Quick Start
Build your first component with nuqs
Framework Adapters
Learn more about adapters and how they work
Parsers
Explore built-in parsers for type-safe state
API Reference
Dive into the complete API documentation