Installation

Install the Package

Install nuqs using your preferred package manager:

npm install nuqs

pnpm add nuqs

yarn add nuqs

bun add nuqs

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.

Wrap your application with the NuqsAdapter in your root layout:

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

Next.js (Pages Router)

Wrap your application in _app.tsx:

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

React (SPA)

For plain React applications (Vite, Create React App, etc.):

src/main.tsx

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.

Wrap your application in the root route:

app/root.tsx

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.

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 Root() {
  return (
    <NuqsAdapter>
      <RouterProvider router={router} />
    </NuqsAdapter>
  )
}

React Router v7

Wrap your application in the root route:

app/root.tsx

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.

src/routes/__root.tsx

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

Click the “Set Test” button and watch the URL update with ?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

Getting Started

Core Concepts

Framework Adapters

Server-Side

Advanced

Migration

Installation

Install the Package

Set Up Your Adapter

Next.js (App Router)

Next.js (Pages Router)

React (SPA)

Remix

React Router v6

React Router v7

TanStack Router

Custom Adapter

Verify Installation

Next Steps

Quick Start

Framework Adapters

Parsers

API Reference

​Install the Package

​Set Up Your Adapter

​Next.js (App Router)

​Next.js (Pages Router)

​React (SPA)

​Remix

​React Router v6

​React Router v7

​TanStack Router

​Custom Adapter

​Verify Installation

​Next Steps

Quick Start

Framework Adapters

Parsers

API Reference

Install the Package

Set Up Your Adapter

Next.js (App Router)

Next.js (Pages Router)

React (SPA)

Remix

React Router v6

React Router v7

TanStack Router

Custom Adapter

Verify Installation

Next Steps