Installation

Install

Install the package alongside its two peer dependencies, react (18 or 19) and nuqs (2+):

npm install @mbsatimov/use-filters nuqs
# or: pnpm add / yarn add / bun add

State is stored in the URL through nuqs, which needs its adapter mounted once at your app's root. This is the only required setup — without it, useFilters throws. Pick the adapter that matches your router:

// app/layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  );
}

// pages/_app.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/pages';

export default function App({ Component, pageProps }) {
  return (
    <NuqsAdapter>
      <Component {...pageProps} />
    </NuqsAdapter>
  );
}

import { NuqsAdapter } from 'nuqs/adapters/react-router/v7';

<NuqsAdapter>
  <RouterProvider router={router} />
</NuqsAdapter>;

import { NuqsAdapter } from 'nuqs/adapters/remix';

<NuqsAdapter>
  <Outlet />
</NuqsAdapter>;

import { NuqsAdapter } from 'nuqs/adapters/react';

<NuqsAdapter>
  <App />
</NuqsAdapter>;

TanStack Router and others are supported too — see the full list in the nuqs adapter docs.

You're set up. Either follow the Quickstart to build a working filtered list, or read How it works to understand the model first.

Install

Mount the nuqs adapter

Next

On this page