> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/47ng/nuqs/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Install nuqs and set up your framework adapter
## Install the Package
Install nuqs using your preferred package manager:
```bash npm theme={null}
npm install nuqs
```
```bash pnpm theme={null}
pnpm add nuqs
```
```bash yarn theme={null}
yarn add nuqs
```
```bash bun theme={null}
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:
```tsx src/app/layout.tsx theme={null}
import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { type ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
{children}
)
}
```
### Next.js (Pages Router)
Wrap your application in `_app.tsx`:
```tsx src/pages/_app.tsx theme={null}
import type { AppProps } from 'next/app'
import { NuqsAdapter } from 'nuqs/adapters/next/pages'
export default function MyApp({ Component, pageProps }: AppProps) {
return (
)
}
```
### React (SPA)
For plain React applications (Vite, Create React App, etc.):
```tsx src/main.tsx theme={null}
import { createRoot } from 'react-dom/client'
import { NuqsAdapter } from 'nuqs/adapters/react'
import App from './App'
createRoot(document.getElementById('root')!).render(
)
```
### Remix
Requires @remix-run/react version 2 or higher.
Wrap your application in the root route:
```tsx app/root.tsx theme={null}
import { NuqsAdapter } from 'nuqs/adapters/remix'
import { Outlet } from '@remix-run/react'
export default function App() {
return (
)
}
```
### React Router v6
Requires react-router-dom version 6.
```tsx src/main.tsx theme={null}
import { NuqsAdapter } from 'nuqs/adapters/react-router/v6'
import { createBrowserRouter, RouterProvider } from 'react-router-dom'
import App from './App'
const router = createBrowserRouter([
{
path: '/',
element:
}
])
export function Root() {
return (
)
}
```
### React Router v7
Wrap your application in the root route:
```tsx app/root.tsx theme={null}
import { NuqsAdapter } from 'nuqs/adapters/react-router/v7'
import { Outlet } from 'react-router'
export default function App() {
return (
)
}
```
### TanStack Router
TanStack Router support is experimental and does not yet cover TanStack Start.
```tsx src/routes/__root.tsx theme={null}
import { NuqsAdapter } from 'nuqs/adapters/tanstack-router'
import { Outlet, createRootRoute } from '@tanstack/react-router'
export const Route = createRootRoute({
component: () => (
)
})
```
### Custom Adapter
If you're using a different router or framework, you can create a custom adapter. See the [Custom Adapter](/adapters/custom) guide for details.
## Verify Installation
You're all set! Let's verify everything works by creating a simple component:
```tsx 'use client' // Only needed for Next.js App Router theme={null}
import { useQueryState } from 'nuqs'
export default function TestComponent() {
const [test, setTest] = useQueryState('test')
return (
Value: {test || 'none'}
)
}
```
Click the "Set Test" button and watch the URL update with `?test=hello`!
## Next Steps
Build your first component with nuqs
Learn more about adapters and how they work
Explore built-in parsers for type-safe state
Dive into the complete API documentation