useSearchParamsの使い方：URLの検索条件を読み書きする
useSearchParamsで検索条件を読み、URLSearchParamsのコピーで更新する方法を解説します。静的ページのSuspenseと、複数値の扱いも確認します。
useSearchParamsで検索条件を読み、URLSearchParamsのコピーで更新する方法を解説します。静的ページのSuspenseと、複数値の扱いも確認します。
対象環境と役割
App Routerで使う機能
この記事のApp Routerの例はNext.js 15以降の非同期リクエストAPIに合わせた書き方です。Next.js 16ではCache Componentsを有効にしない構成を前提とします。Pages Routerの記事とは配置先・実行場所が異なるため、プロジェクトのルーターとバージョンを先に確認してください。
TypeScriptの例は5.2以降と、利用するNext.jsが対応するNode.jsを前提にします。app/layout.tsx を備えたApp Routerプロジェクトで実行してください。
引数・戻り値・受け渡すデータ
戻り値は読み取り専用の検索パラメーターです。get は最初の値またはnull、getAll は同じ名前の値の配列を返します。書き換えるときはコピーを作成します。
コード例を動かす
app/query-demo/page.tsx を作成する
以下はこのファイルとして配置する例です。既存ファイルへ追記する場合は、同じ名前のexportやURLが重複しないように統合してください。
'use client';
import { Suspense } from 'react';
import { useRouter, usePathname, useSearchParams } from 'next/navigation';
function QueryControls() {
const router = useRouter();
const pathname = usePathname();
const searchParams = useSearchParams();
const sort = searchParams.get('sort') === 'old' ? 'old' : 'new';
function changeSort() {
const next = new URLSearchParams(searchParams.toString());
next.set('sort', sort === 'new' ? 'old' : 'new');
router.replace(`${pathname}?${next.toString()}`);
}
return <><p>並び順: {sort}</p><button onClick={changeSort}>並び順を変更</button></>;
}
export default function QueryDemo() {
return <main><h1>検索条件</h1><Suspense fallback={<p>条件を読み込み中</p>}>
<QueryControls />
</Suspense></main>;
}実行結果と処理の順序
/query-demo?tag=react を開いてボタンを押すと、tagを残したままsortが追加されます。新しいオブジェクトを作ることで読み取り専用の値を直接変更せずに済みます。
SuspenseはHookを呼ぶ子コンポーネントの外側に置きます。同じ関数でHookを呼んだ後に戻り値のJSXをSuspenseで囲むだけでは、そのHookの実行を囲めません。
つまずきやすい点と使い分け
開発では動いても本番ビルドで失敗する
静的ページでこのHookを使う場合、本番ビルドではSuspense境界が必要です。開発サーバーだけの動作確認で完了しないようにします。
サーバー側のsearchParamsとの違い
Pageに渡される searchParams はPromiseで解決する通常のオブジェクトです。このHookの戻り値と同じ型やメソッドを持つわけではありません。URLの値は認可やDBクエリの安全性を保証しません。
静的出力で使えるか
ブラウザーでの処理は静的サイトでも利用できます。ただし遷移先のページは事前に生成されている必要があり、クライアントでの操作がサーバー機能や認可の代わりになるわけではありません。
確認課題と実務への応用
自分で値を変えて確認する
同じtagを複数指定してgetとgetAllを比較します。sort以外の条件が消えていないことと、replaceによって戻る履歴が増えないことを確認してください。
開発サーバーだけでなく、本番用ビルドと公開先でも確認します。URLを直接開く場合と画面内のリンクから遷移する場合、値がない場合と不正な値の場合を分けて試すと、型だけでは防げない入力の問題が見つかります。
公式資料と関連する記事
Googleの優先するニュース提供元にSEの部屋を追加
Googleで、いつも読みたい情報源を選べます。登録可否はGoogleの画面で確認できます。
候補にSEの部屋が表示されない場合は、まだ追加できません。