---
title: "nuqsとは？useQueryStateの使い方と2.10までの新機能・debounceの使いどころ"
url: "https://www.issoh.co.jp/tech/details/8535/"
published: 2025-09-01
updated: 2026-10-31
categories: ["React"]
publisher: "株式会社一創"
---

# nuqsとは？useQueryStateの使い方と2.10までの新機能・debounceの使いどころ

nuqs（作者は「nucks」と、ducksと韻を踏む読み方をしています）は、URLのクエリ文字列をReactの`useState`と同じ書き方で読み書きできるライブラリです。`?page=3&sort=new`のような値を型付きのstateとして扱え、再読み込みやURLの共有でも画面の状態が残ります。2026年10月31日時点の最新版は**2.10.2**（2026-10-08公開）です。この記事では、導入手順、既定値の意味、debounceが効く条件、テストの書き方、2.5〜2.10の変更点を説明します。挙動はNode.js 26.5.0・React 19.3.0・nuqs 2.10.2で、jsdom上のtestingアダプター（`nuqs/adapters/testing`）を使って実測し、掲載コードはTypeScript 7.0.2の`strict`で型検査、テストコードはVitest 5.0.5で実行しました。実ブラウザやNext.jsアプリ上での動作は公式ドキュメントの記述に拠っています。

## まとめ：nuqs 2.10の要点と使いどころ

- 最新版は2.10.2。公式アダプターはNext.js（14.2以上・App Router／Pages Router）、React SPA、Remix、React Router v6〜v8、TanStack Router（実験的）で、Vue・Svelte向けの公式版はありません。RemixとReact Router v6のアダプターは3.0で削除予定です。
- 使い始めはルートを`NuqsAdapter`で包み、`useQueryState('page', parseAsInteger.withDefault(1))`のようにキーとパーサーを渡すだけです。
- 既定は履歴を置き換え（`history: 'replace'`）、サーバーへ通知しない（`shallow: true`）、スクロールしない、既定値と同じ値ならURLから消す（`clearOnDefault: true`）の4つです。モーダルやタブで戻るボタンを効かせたいキーだけ`history: 'push'`にします。
- URL更新は既定で50ms間隔に間引かれます。debounceは`shallow: false`でサーバーに取りに行く場合の機能で、クライアント側で取得するなら値の側をdebounceします。
- サーバー側は`createLoader`で読み、`createSerializer`でリンクを組み立てます。テストは`withNuqsTestingAdapter`で初期URLを渡し、`onUrlUpdate`で書き込まれたクエリを検証します。
- TanStack Routerを主に使うアプリでは、ルーター自身の型付きsearch paramsを優先するよう公式が勧めています。

## nuqsの役割：useStateの書き方でURLクエリに状態を置く仕組み

Next.jsのApp Routerで検索条件をURLに同期させる場合、`useSearchParams`は読み取り専用なので、書き込みは`router.replace()`か、Next.jsが`useSearchParams`と同期すると明記している`window.history.replaceState`／`pushState`で、URL文字列を組み直して行います。どちらの方法でも、数値や配列と文字列の相互変換は自前です。nuqsはこの「読む・変換する・書き戻す」を1つのフックにまとめます。

作者はフランス在住のFrançois Best氏（GitHubの47ng／franky47）で、リポジトリは2020年5月作成、ライセンスはMITです。[npmのnuqsパッケージ](https://www.npmjs.com/package/nuqs)の週間ダウンロード数は7,936,222件（2026年10月23日〜29日）、GitHubスターは10,899件でした。前身のパッケージ名は`next-usequerystate`で、Next.js専用から始まり、2.0でアダプター方式に変わって他のフレームワークにも広がりました。2024年以前の日本語記事には「Next.js専用」と書かれたものがありますが、2.x系では当てはまりません。

URLに置くのに向くのは、検索語・絞り込み・並び順・ページ番号・タブ・モーダルの開閉など「その画面をURLだけで再現したい」状態です。入力途中のフォーム全体や認証情報のような、共有されると困る値・長い値は置きません（判断の詳細は後半の「nuqsを選ばない方がよい場面」で扱います）。

## nuqsの導入手順：インストールとアダプターの設定

インストールは`npm install nuqs`（pnpm・yarn・bun・Denoも可）です。2.x系はフレームワークごとの`NuqsAdapter`でアプリを包む方式で、アダプターが無いまま`useQueryState`を呼ぶと`nuqs requires an adapter to work with your framework.`というエラーで止まります。このエラーが出たら、`NuqsAdapter`がフックを使うコンポーネントより上の階層にあるか、使っているフレームワークに合ったimport元かを確認します。

| フレームワーク               | import元                           | 対応バージョン                       |
| --------------------- | --------------------------------- | ----------------------------- |
| Next.js App Router    | `nuqs/adapters/next/app`          | next 14.2.0以上                 |
| Next.js Pages Router  | `nuqs/adapters/next/pages`        | next 14.2.0以上                 |
| React SPA（Viteなど）     | `nuqs/adapters/react`             | react 18.3／19                 |
| Remix（3.0で削除予定）       | `nuqs/adapters/remix`             | @remix-run/react 2            |
| React Router v6／v7／v8 | `nuqs/adapters/react-router/v6`など | 各メジャー版                        |
| TanStack Router       | `nuqs/adapters/tanstack-router`   | @tanstack/react-router 1（実験的） |
| テスト（Vitest等）          | `nuqs/adapters/testing`           | –                             |

対応バージョンは[公式のInstallationページ](https://nuqs.dev/docs/installation)の表記で、Next.js 14.2未満は旧系列の`nuqs@^1`を使います。v8向けは2.9.0で追加されました。[公式のAdaptersページ](https://nuqs.dev/docs/adapters)は、React Router v6向けと、v6を指す汎用の`nuqs/adapters/react-router`、Remix向けを、上流がサポートを終えたとして3.0で削除すると予告しているため、新規ならv7かv8のアダプターを選びます。2.8.0の「React Router v5対応」は`peerDependencies`の範囲を広げてインストールで失敗しないようにした変更で、v5用アダプター自体は本体に含まれず、shadcnのレジストリから入れる簡易版です（PR #1214の説明によると、浅い更新への追従やキー分離は備えていません）。上の表に無いルーター向けには`nuqs/adapters/custom`で独自アダプターを作れます。

### Next.js App Routerでの設定とSuspenseの扱い

ルートの`layout.tsx`で`children`を包みます。App Routerの`NuqsAdapter`はServer Componentのlayoutからそのまま使えます（App Routerのファイル規約は[App Routerとは？Next.jsのファイル規約・動的ルーティング・Pages Routerとの違い](/tech/details/4026/)で解説しています）。

```
// app/layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { type ReactNode } from 'react'

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="ja">
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  )
}
```

ビルド時に`Missing Suspense boundary with useSearchParams`が出たら、`useQueryState`を使うクライアントコンポーネントをページ側で`<Suspense>`に入れます。nuqsは内部でNext.jsの`useSearchParams`を読むため、静的レンダリングされるページではこの境界が必要です。

### React SPA・React Router・TanStack Routerでの違い

React SPAでは`main.tsx`で`<App />`を包みます。サーバーが無い構成なので`shallow: false`は効きません。2.4.0からはサーバー側で描画し直したい場合に、アダプターへ`fullPageNavigationOnShallowFalseUpdates`を渡すと全ページ遷移に切り替えられます。2.10.0では同じReactアダプターに`serverSearch`が加わり、AstroやHono、Fastifyのように`location`が無いサーバー描画でも、リクエストのクエリ文字列を初期値として渡せるようになりました。

React Router系とRemixは既定で`shallow: true`なので、loaderを再実行させたいキーにだけ`shallow: false`を付けます。TanStack Routerのアダプターは公式が実験的と明記しており、TanStack Startはまだ対象外です（[TanStack Routerの型安全ルーティング](/tech/details/9913/)を主に使う場合の考え方は後半で触れます）。

## useQueryStateとuseQueryStatesの使い方

基本形は`const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))`です。第1引数がURLのキー、第2引数がパーサーで、戻り値は`useState`と同じく値と更新関数の組です。パーサーを省くと値は`string | null`になり、`setPage(null)`でキーがURLから消えます。

### パーサーの解析失敗時の挙動と既定値

組み込みパーサーは`parseAsString`・`parseAsInteger`・`parseAsFloat`・`parseAsBoolean`・`parseAsIsoDate`・`parseAsTimestamp`・`parseAsStringLiteral`・`parseAsJson`・`parseAsArrayOf`など15種類です（2.10.2の`nuqs`のexportのうち`parseAs`で始まるものを数えた値で、独自パーサーを作る`createParser`などは含みません）。testingアダプターで動かした結果は次のとおりでした。ここでの「解析失敗」は文字列を型に変換できない場合のことで、値が業務上妥当かどうかの検証は別に行う必要があります。

- `?page=abc`を`parseAsInteger.withDefault(1)`で読むと`1`が返る（例外にならず既定値に落ちる）。
- `setPage(3)`でURLは`?page=3`、`setPage(1)`で既定値と一致するためキーごと消えて空文字になる。
- `setPage(1, { clearOnDefault: false })`なら`?page=1`が残る。

既定値の変更でURLの意味が変わるのを避けたいページ（共有リンクを長く残す一覧など）では、`clearOnDefault: false`を付けて値を明示的に残す方が安全です。

### 複数キーをまとめるuseQueryStatesとurlKeys

ページ番号と並び順のように一緒に変わるキーは`useQueryStates`でまとめます。1回の呼び出しで複数キーを更新しても、URL更新は1回にまとまります。`urlKeys`を使うとコード上の名前とURL上の短いキーを分けられます。

```
'use client'
import { useQueryStates, parseAsInteger, parseAsStringLiteral } from 'nuqs'

const sortOrders = ['new', 'old'] as const

export function useListParams() {
  return useQueryStates(
    {
      page: parseAsInteger.withDefault(1),
      sort: parseAsStringLiteral(sortOrders).withDefault('new'),
    },
    { urlKeys: { page: 'p' } }
  )
}
```

このフックで`?p=5&sort=bad`を読むと`{ page: 5, sort: 'new' }`になり、リストに無い`bad`は既定値に置き換わりました。`setParams({ page: 9, sort: 'old' })`で`?p=9&sort=old`、`setParams(null)`ではこのフックが管理する`p`と`sort`だけが消え、管理外のキー（例：`other=x`）はURLに残りました。`sort`の型はtsc 7.0.2で`'new' | 'old'`と推論されました。2.5.0でリテラル系パーサーの引数に`const`修飾子が付いたため、`parseAsStringLiteral(['new', 'old'])`のように配列を直接渡しても同じリテラル型になります。

注意点として、同じキーに別のパーサーを使うフックが2つあると、最後の更新が両方に伝わります。[公式のトラブルシューティング](https://nuqs.dev/docs/troubleshooting)にある例では、`parseAsInteger`で読んでいる側にも`1.234`が入ります。キーとパーサーの組は上のような専用フックに閉じ込めておくのが確実です。

### 配列の2つの書式：parseAsArrayOfとparseAsNativeArrayOf

配列には書式が2つあります。`parseAsArrayOf(parseAsString)`は`?tags=a,b`のように区切り文字で1キーに詰め、2.7.0で入ったマルチパーサーの`parseAsNativeArrayOf`は`?tag=a&tag=b`のように同じキーを繰り返します。後者はHTMLフォームのGET送信やバックエンドのフレームワークが標準で解釈する形式なので、既存APIにクエリをそのまま渡す場合はこちらが合います。

## オプションの既定値：history・shallow・scroll・clearOnDefault

オプションはパーサーの`.withOptions()`、フックの第2引数、更新関数の第2引数のどこでも指定でき、呼び出し時の指定が最優先です。2.10.2で確認した既定値は次の4つです。

| オプション            | 既定値         | 変えたときの動き               |
| ---------------- | ----------- | ---------------------- |
| `history`        | `'replace'` | `'push'`で更新ごとに履歴を追加    |
| `shallow`        | `true`      | `false`でRSC・loaderを再実行 |
| `scroll`         | `false`     | `true`で更新時にページ先頭へ      |
| `clearOnDefault` | `true`      | `false`で既定値もURLに残す     |

`shallow: true`はNext.jsの浅いルーティングと同じ意味で、URLだけ書き換えてサーバーには知らせません。Server Componentで検索結果を描くページなら、そのキーだけ`shallow: false`にします。`clearOnDefault`は1.x系では`false`が既定で、2.0.0で`true`に変わりました。1.x時代の記事のコードをそのまま写すと、既定値がURLに出なくなる差が出ます。

2.5.0からは`NuqsAdapter`の`defaultOptions`でアプリ全体の既定を変えられ、`history`は2.9.0で対象に加わりました。

### モーダル・タブで戻るボタンを効かせるhistory: ‘push’

詳細モーダルを開いた状態をURLに残し、ブラウザの戻るボタンで閉じられるようにするには、そのキーだけ`history: 'push'`にします。

```
'use client'
import { useQueryState, parseAsBoolean } from 'nuqs'

export function useDetailModal() {
  const [open, setOpen] = useQueryState(
    'detail',
    parseAsBoolean.withDefault(false).withOptions({ history: 'push' })
  )
  return {
    open,
    show: () => setOpen(true),
    close: () => setOpen(null, { history: 'replace' }),
  }
}
```

testingアダプターで`show()`→`close()`の順に呼ぶと、URL更新は`?detail=true`（`history: 'push'`）と空文字（`'replace'`）の2回でした。閉じる側を`replace`にしているのは、`setOpen(null)`のままだと閉じる操作も`'push'`で履歴を1つ積み（同じ実測で確認）、戻るボタンでモーダルが再び開いてしまうためです。[公式のOptionsページ](https://nuqs.dev/docs/options)は、戻るボタンの挙動を変えるのはタブやモーダルのような画面遷移に近い操作に限るよう警告しています。`defaultOptions`で`'push'`を全体に設定すると、検索語の1文字ごとに履歴が増えます。

### shallow: falseとuseTransitionによる読み込み状態の表示

`shallow: false`でServer Componentを描き直すと、新しい結果が届くまで画面は古いままです。Reactの`useTransition`が返す`startTransition`をオプションに渡すと、その間`isPending`が`true`になり、読み込み中の表示を出せます。

```
'use client'
import { useTransition, type ReactNode } from 'react'
import { useQueryState, parseAsString } from 'nuqs'

export function ResultsPane({ children }: { children: ReactNode }) {
  const [isPending, startTransition] = useTransition()
  const [category, setCategory] = useQueryState(
    'category',
    parseAsString.withDefault('all').withOptions({ shallow: false, startTransition })
  )
  return (
    <section aria-busy={isPending}>
      <select value={category} onChange={(e) => setCategory(e.target.value)}>
        <option value="all">すべて</option>
        <option value="book">書籍</option>
      </select>
      {isPending ? <p>読み込み中…</p> : children}
    </section>
  )
}
```

このコードはtsc 7.0.2の`strict`で型エラーなしでした。1.x系では`startTransition`を渡すと`shallow: false`が自動で付きましたが、2.x系では明示が必要です。React Router v7以降のデータルーターでは、React 19と組み合わせるとloaderの完了まで`isPending`が続きます。2.10.2では、トランジション中の更新が同期描画に割り込まれたときに値が`null`と新しい値の間でちらつく不具合（issue #1567）が修正されたため、`startTransition`を使っているなら2.10.2へ上げておきます。

## URL更新の間引き：throttleとdebounceの使い分け

ブラウザはHistory APIの呼び出し回数を制限しているため、nuqsはURL更新をキューに溜めて間引きます。既定のthrottleは50msで、Safari 17以上は120ms、それより古いSafariは320msです（2.10.2のソースはUser-Agentの`Safari`の版でこの値を切り替えています）。testingアダプターで同じティックに3回`setQ`を呼んだところ、URL更新は最後の値で1回だけでした。

2.5.0で`throttleMs`は非推奨になり、`limitUrlUpdates: throttle(1000)`の書き方に移りました。同じ`limitUrlUpdates`に`debounce(ms)`を渡すと、最後の入力から指定時間たってからURLを更新します。300msのdebounceで「r」「re」「rea」を100ms間隔で入力した実測では、stateは即座に`rea`になり、URL更新は最後の入力の約330ms後に`?q=rea`の1回だけでした。

### サーバー取得を抑えるdebounceとshallow: falseの組み合わせ

URLの更新を遅らせることと、データの取得を遅らせることは別の話です。公式は、debounceが意味を持つのは`shallow: false`と組み合わせてRSCやloaderでサーバー側取得をする場合だけで、TanStack Queryなどでクライアント側取得をするなら、フックが返すstateの側を別のdebounceフックで遅らせるよう案内しています。stateは常に即時更新されるため、URLだけdebounceしてもクライアント側の取得回数は減りません。2.6.0からは`shallow: true`とdebounceを組み合わせると開発時に警告が出ます。

```
'use client'
import { useQueryState, parseAsString, debounce } from 'nuqs'

export function SearchBox() {
  const [q, setQ] = useQueryState(
    'q',
    parseAsString.withDefault('').withOptions({ shallow: false })
  )
  return (
    <input
      type="search"
      aria-label="検索語"
      value={q}
      onChange={(e) =>
        setQ(e.target.value, {
          limitUrlUpdates: e.target.value === '' ? undefined : debounce(500),
        })
      }
    />
  )
}
```

空にしたときだけ即時更新にしているのは公式の例と同じ考え方で、入力を消した直後に結果を戻すためです。debounceを途中で解除したい呼び出しには`defaultRateLimit`を渡します。

## サーバー側での読み取り：createLoader・createSearchParamsCache・createSerializer

サーバー側のAPIは`nuqs/server`から読み込みます。クライアントと同じパーサー定義を1ファイルに置けば、URLの形式がずれません。

```
// app/search/searchParams.ts
import { createLoader, createSerializer, parseAsInteger, parseAsString } from 'nuqs/server'

export const searchParams = {
  q: parseAsString.withDefault(''),
  page: parseAsInteger.withDefault(1),
}
export const loadSearchParams = createLoader(searchParams)
export const serialize = createSerializer(searchParams)

// app/search/page.tsx
import type { SearchParams } from 'nuqs/server'
import { loadSearchParams, serialize } from './searchParams'

type PageProps = { searchParams: Promise<SearchParams> }

export default async function Page({ searchParams }: PageProps) {
  const { q, page } = await loadSearchParams(searchParams)
  const next = serialize('/search', { q, page: page + 1 })
  return <a href={next}>{q} の {page + 1} ページ目へ</a>
}
```

このコードはtsc 7.0.2の`strict`で型エラーなしでした。`createLoader`はURL文字列・`URLSearchParams`・オブジェクト・それらのPromiseを受け取ります。実測では、`loadSearchParams('https://ex.com/?page=4&q=nuqs')`は`{ q: 'nuqs', page: 4 }`を返し、`{ page: 'x' }`のような変換できない値は`page: 1`の既定値に落ちました。不正な値で例外を投げたい場合は、2.5.0で入った`{ strict: true }`を第2引数に渡します。

ページより深いServer Componentで同じ値を読む方法は2つあります。propsで順に渡すか、`createSearchParamsCache`で1リクエスト内だけ有効なキャッシュを作るかです。後者はページで`await cache.parse(searchParams)`を先に呼び、子のServer Componentでは`cache.get('q')`や`cache.all()`で読みます（Next.js App RouterのServer Component専用で、Client Componentからは使えません）。階層が浅いならpropsで十分です。`createSerializer`は`clearOnDefault`を既定で`true`として扱うため、`serialize({ page: 1 })`は空文字になり、`{ page: 2 }`で`?page=2`を返しました。

## nuqsを使うコンポーネントのテスト：withNuqsTestingAdapterとVitest

nuqs 2.x系は、テスト用のアダプター`nuqs/adapters/testing`を同梱しています。ルーターやURLをモックせずに、初期のクエリ文字列を渡し、書き込まれたURLを`onUrlUpdate`で受け取って検証できます。`renderHook`向けの`withNuqsTestingAdapter`は2.2.0で入りました。前の章の`useListParams`を検証するテストは次のとおりで、Vitest 5.0.5（jsdom環境）で通りました。Vitest自体の設定は[Vitestの使い方と書き方](/tech/details/2867/)で扱っています。

```
import { renderHook, act } from '@testing-library/react'
import { withNuqsTestingAdapter, type UrlUpdateEvent } from 'nuqs/adapters/testing'
import { expect, it } from 'vitest'
import { useListParams } from './useListParams'

it('ページ送りでpだけが更新される', async () => {
  const updates: UrlUpdateEvent[] = []
  const { result } = renderHook(() => useListParams(), {
    wrapper: withNuqsTestingAdapter({
      searchParams: '?p=2&sort=old',
      onUrlUpdate: (e) => updates.push(e),
    }),
  })
  expect(result.current[0]).toEqual({ page: 2, sort: 'old' })
  await act(() => result.current[1]({ page: 3 }))
  expect(updates).toHaveLength(1)
  expect(updates[0]!.queryString).toBe('?p=3&sort=old')
  expect(updates[0]!.options.history).toBe('replace')
})
```

`onUrlUpdate`が受け取るイベントには、`searchParams`（`URLSearchParams`）、`queryString`、更新に使われた`options`が入ります。`history`や`shallow`の指定が意図どおり渡ったかまで確かめられるので、前の章のモーダルのように`'push'`を使うキーはここで固定しておきます。

つまずきやすいのは、testingアダプターが既定でURLを記憶しない点です。[公式のTestingページ](https://nuqs.dev/docs/testing)のとおり、更新は毎回初期のクエリ文字列を土台に組み立てられます。`?page=2`から始めて`{ q: 'a' }`→`{ page: 5 }`と2回更新した実測では、2回目のURLは`?page=5`で、1回目の`q=a`は含まれませんでした（フックのstateは`{ page: 5, q: 'a' }`）。`hasMemory: true`を渡すと2回目は`?page=5&q=a`になり、実際のアダプターと同じく更新が積み重なります。複数の操作を続けて検証するテストでは`hasMemory: true`を付けます。また、testingアダプターは既定でthrottleの待ち時間を0にしています（`rateLimitFactor`の既定値が0）。throttleの間隔まで検証するなら`rateLimitFactor: 1`を渡します。debounceはこの係数の影響を受けず、テスト中も指定した時間だけ待ちます。

## nuqs 2.5〜2.10の新機能と変更点

2.5.0から2.10.0まで、マイナー版は6つ出ています。日付は[GitHub Releases](https://github.com/47ng/nuqs/releases)の公開日です。

| 版      | 公開日        | 主な変更                                          |
| ------ | ---------- | --------------------------------------------- |
| 2.5.0  | 2025-08-22 | debounce、キー分離、Standard Schema、TanStack Router |
| 2.6.0  | 2025-09-05 | processUrlSearchParams、debounce警告             |
| 2.7.0  | 2025-09-30 | マルチパーサー、testingのmemory                        |
| 2.8.0  | 2025-11-17 | React Router v5の依存範囲を許容                       |
| 2.9.0  | 2026-06-30 | React Router v8対応、defaultOptionsにhistory      |
| 2.10.0 | 2026-08-20 | ReactアダプターのserverSearch                       |
| 2.10.1 | 2026-08-25 | 不具合修正3件                                       |
| 2.10.2 | 2026-10-08 | 不具合修正2件（npm latest）                           |

2.5.0では他に`NuqsAdapter`の`defaultOptions`とリテラル型パーサーの`const`修飾子が入り、`throttleMs`が非推奨になりました。2.6.0の`processUrlSearchParams`は、URLに書き出す直前のクエリをアプリ側で加工する仕組みです。2.10.1は、初回描画でURLに値があるときに描画が1回で済むようにする修正など3件、[2.10.2](https://github.com/47ng/nuqs/releases/tag/v2.10.2)はトランジション中の値のちらつきと、別のキーを続けて浅く更新したときにもう一方の値が一時的に`null`へ戻る問題（Next.js 16.4で報告されたissue #1612）の2件を直しました。

2026年10月31日時点で3.0は公開されていません（npmのbetaタグは2.10.2-beta.1で、latestより前の版です）。公式のAdaptersページは3.0でRemix・React Router v6・汎用`nuqs/adapters/react-router`の各アダプターを削除すると予告しており、作者の2025年の振り返りでは、2026年の目標として実行時にStandard Schemaで検証する3.0と、コアを単一ストアへ書き直すことが挙がっています。

### キー分離（Key Isolation）の対応範囲：Next.jsは対象外

キー分離は、URLのあるキーを読むコンポーネントが、そのキーの値が変わったときだけ再描画される仕組みです。無い場合、URLのどこかが変わるたびにURLを読む全コンポーネントが再描画されます。[2.5.0の公式ブログ](https://nuqs.dev/blog/nuqs-2.5)が挙げる対応アダプターはReact SPA、React Router（v6・v7）、Remix、TanStack Routerで、Next.jsは含まれていません。Next.jsは`URLSearchParams`を1つのContextで配っており、どのキーが変わっても`useSearchParams`の呼び出し元が全部再描画されるためです。2.10.2の配布物でも、キー分離のモジュールを読み込んでいるのはReactアダプターとReact Router系の共通実装で、Next.js用の実装は読み込んでいませんでした。Next.jsでフィルタ項目の多い画面を作る場合は、URLを読むコンポーネントを小さく分けて再描画の範囲を絞ります。

### Standard Schema対応とTanStack Routerでの使い方

`createStandardSchemaV1`はパーサーの組からStandard Schema準拠の検証器を作ります。実測では`{ page: '3', q: 'x' }`を渡すと`{ value: { page: 3, q: 'x' } }`が返り、`page: 'abc'`では`issues`にエラーが入りました。用途は、TanStack Routerの`validateSearch`やtRPCの入力検証のように、Standard Schemaを受け付けるツールへ同じ定義を渡すことです。仕様そのものは[Standard Schemaとは？Zod・Valibot・ArkTypeを共通で受け取る仕組み](/tech/details/11777/)で解説しています。

TanStack Routerについて公式ブログは、ルーター自身の型付きsearch paramsのAPIを使うよう勧めたうえで、nuqsを使ったコンポーネントをnpmや共有ライブラリから読み込む場合の互換手段としてアダプターを位置づけています。

## nuqsを選ばない方がよい場面

nuqsは「URLが状態の正本である」画面には強い一方、次の条件では採用しない判断をすべきです。

- **アプリ全体がTanStack Router**：ルーターの`validateSearch`と`useSearch`で型付きのsearch paramsが揃っており、URLの状態管理だけが目的ならnuqsは原則不要です。nuqsで書かれた既存コンポーネントを再利用する場合が例外です。
- **URLが長くなる状態**：[公式のLimitsページ](https://nuqs.dev/docs/limits)は2,000文字を超えるなら設計を見直す目安としています。フォームの下書きや大きなJSONは[Zustandなどの状態管理ライブラリ](/tech/details/7615/)やサーバー側に置きます。
- **共有されてはいけない値**：URLは履歴・ログ・Refererに残ります。トークンや個人情報は置きません。
- **クライアント取得の回数を減らしたいだけ**：前述のとおりURLのdebounceでは減りません。[TanStack Query](/tech/details/10307/)のキーに渡す値をdebounceします。

検索エンジン向けには、表示内容を変えないクエリ（UIの開閉など）だけを持つページならクエリを除いたcanonicalを指定し、内容を決めるクエリ（商品IDなど）ならcanonicalにも含める、というのが[公式のSEOページ](https://nuqs.dev/docs/seo)の方針です。後者は`createSerializer`でcanonical URLを組み立てられます。操作の順番でキーの並びが変わり、同じ内容のURLが何通りもできるのが気になる場合は、`NuqsAdapter`の`processUrlSearchParams`で`search.sort()`を呼んでキーを常にアルファベット順に並べます。検索・絞り込みの多い業務画面を、URL設計から含めて作りたい場合は、弊社の[業務用・Webアプリ開発](/service/apps/business/)でもご相談を受けています。

## よくある質問

### nuqsはVueやSvelteでも使えますか？

使えません。nuqsはReact向けで、公式アダプターもReact系フレームワークだけです。作者は2026年の目標としてコアの単一ストア化を挙げ、それによりSolid・Svelte・Vue版も理論上は可能になるとしつつ、React側の保守だけで手一杯だとも書いています。

### nuqsはTanStack Startで使えますか？

2.10.2時点では公式の対象外です。TanStack Router向けのアダプター（`nuqs/adapters/tanstack-router`）は実験的な扱いで、公式のAdaptersページはTanStack Startにはまだ対応していないと明記しています。TanStack Startでは、ルーターの`validateSearch`と`useSearch`でsearch paramsを扱う方が確実です。

### shallowオプションは何を切り替えますか？

URLを書き換えたときにサーバーへ知らせるかどうかです。既定の`true`はURLだけ更新し、`false`でNext.jsのServer ComponentやReact Router・Remixのloaderが再実行されます。React SPAでは効果がありません。

### NuqsAdapterを入れないとどうなりますか？

`nuqs requires an adapter to work with your framework.`というエラーで止まります。2.x系はアダプターが必須で、Next.js App Routerならルートの`layout.tsx`を`nuqs/adapters/next/app`の`NuqsAdapter`で包みます。

### nuqsはReact Routerで使えますか？

使えます。公式アダプターはv6・v7・v8の版ごとにあり、v6向けは3.0で削除予定なので、新規ならv7かv8を使います。loaderで値を使うキーには`shallow: false`を付けます。

## 関連記事

- [App Routerとは？Next.jsのファイル規約・動的ルーティング・Pages Routerとの違い](/tech/details/4026/)
- [TanStack Routerとは？型安全ルーティングの特徴・導入手順とReact Routerとの違い](/tech/details/9913/)
- [Vitestの使い方と書き方：読み方・設定からReact Testing Libraryのコンポーネントテストまで【Vitest 5対応】](/tech/details/2867/)
- [TanStack Queryとは？React Queryとの違い・v5の使い方と既定値の落とし穴](/tech/details/10307/)
- [Standard Schemaとは？Zod・Valibot・ArkTypeを共通で受け取る仕組みと実装例](/tech/details/11777/)

---

出典: [nuqsとは？useQueryStateの使い方と2.10までの新機能・debounceの使いどころ](<https://www.issoh.co.jp/tech/details/8535/>)（株式会社一創）
