Day 47:URLパラメータを使った検索機能を作る
Day 47では、Next.js App RouterでURLパラメータを使った検索機能を作ります。今日は、/products?keyword=react のようなURLを使って、検索キーワードに応じて商品一覧を絞り込む仕組みを、初心者向けに順番に理解していきます。App Routerでは、Server Componentのページで searchParams を受け取り、Client Componentでは useSearchParams、usePathname、useRouter を使ってURLを書き換えるのが基本です。useSearchParams は読み取り専用で、Client Component専用のHookです。(🔗 nextjs.org)
この機能のよいところは、検索条件がURLに残ることです。つまり、検索した状態のURLをそのまま共有できますし、再読み込みしても同じ検索結果を再現しやすくなります。また、ページ側で searchParams を使ってデータ取得や絞り込みを行うのが、Next.js公式でも推奨される基本パターンです。(🔗 nextjs.org)
- まず理解したいこと
- 今日作る完成イメージ
- Step 1:検索対象のデータを用意する
- Step 2:searchParams を使って検索するページを作る
- Step 3:検索フォームをClient Componentで作る
- Step 4:なぜServer Component側で絞り込むのか
- Step 5:/products?keyword=react がどう動くのかを追いかける
- Step 6:検索条件を消したときの設計も重要
- Step 7:router.push と router.replace の違いも知っておく
- Step 8:部分一致検索をどう実装しているか
- Step 9:検索結果が0件のときも必ず考える
- Step 10:実務で特に大事な注意点
- Step 11:リアルタイム検索に発展させる考え方
- Step 12:初心者向けテンプレート
- Day 47のチェックリスト
- まとめ
まず理解したいこと
検索機能といっても、今回やることはとてもシンプルです。URLの ? 以降にあるクエリ文字列を読み取り、その値で配列データを絞り込みます。たとえば、/products?keyword=react なら、keyword という名前の検索条件に react が入っている、という意味です。ページ側では searchParams からその値を読み、フォーム側ではURLを書き換えます。Next.jsでは、Server Componentのページは searchParams prop を受け取れ、Client Componentでは useSearchParams() で現在のクエリ文字列を読めます。(🔗 nextjs.org)
- 検索条件を読む場所は、基本的に `page.tsx` です。
- 入力欄の操作は、基本的に Client Component で行います。
- 検索条件をURLに反映するには、`useRouter()` や `Link` を使います。
- 一覧の絞り込み自体は、Server Component側で行うと整理しやすいです。
今日作る完成イメージ
今日は、/products ページに検索フォームを置き、入力したキーワードをURLに反映して一覧を絞り込みます。完成後のURLは、たとえば次のようになります。
/products
/products?keyword=react
/products?keyword=next
/products?keyword=typescript
今回のファイル構成は次のようにします。
src/
├── app/
│ ├── products/
│ │ ├── SearchForm.tsx
│ │ └── page.tsx
│ └── layout.tsx
└── data/
└── products.ts
Step 1:検索対象のデータを用意する
まずは検索対象となる商品データを用意します。今回は学習用なので、データベースではなく配列で十分です。
src/data/products.ts
// 商品1件分の型です
export type Product = {
id: number;
name: string;
description: string;
};
// 学習用の商品データです
export const products: Product[] = [
{
id: 1,
name: "React入門書",
description: "Reactの基本を学べる初心者向けの書籍です。",
},
{
id: 2,
name: "Next.js実践ガイド",
description: "App Routerやデータ取得を学べる実践向けの書籍です。",
},
{
id: 3,
name: "TypeScriptハンドブック",
description: "型安全な開発を学びたい方向けの書籍です。",
},
{
id: 4,
name: "React Tシャツ",
description: "Reactロゴ入りの学習用Tシャツです。",
},
{
id: 5,
name: "JavaScriptノート",
description: "フロントエンド学習メモに便利なノートです。",
},
];TypeScriptここでは、name だけでなく description も持たせています。こうしておくと、「商品名だけでなく説明文も検索対象にする」という実践的な練習ができます。
Step 2:searchParams を使って検索するページを作る
次に、/products ページを作ります。App Routerのページでは、searchParams prop を受け取れます。現在のNext.js公式では、searchParams はPromiseとして受け取る形が案内されており、Server Componentのページで検索条件を使ってデータ取得や絞り込みを行うのに向いています。また、searchParams を使うとそのページは動的レンダリングになります。(🔗 nextjs.org)
src/app/products/page.tsx
// 商品データを読み込みます
import { products } from "../../data/products";
// 検索フォームを読み込みます
import SearchForm from "./SearchForm";
// searchParamsの型です
type ProductsPageProps = {
searchParams: Promise<{
keyword?: string;
}>;
};
// 商品一覧ページです
export default async function ProductsPage({
searchParams,
}: ProductsPageProps) {
// URLからkeywordを取得します
const { keyword = "" } = await searchParams;
// 比較しやすいように小文字へ変換します
const normalizedKeyword = keyword.trim().toLowerCase();
// 商品一覧をキーワードで絞り込みます
const filteredProducts = products.filter((product) => {
// 商品名と説明文をまとめて小文字化します
const targetText =
`${product.name} ${product.description}`.toLowerCase();
// キーワードが空なら全件表示し、入っていれば部分一致検索します
return normalizedKeyword === ""
? true
: targetText.includes(normalizedKeyword);
});
return (
<main>
<h1>商品一覧</h1>
<p>
URLパラメータを使って商品を検索します。
</p>
{/* 現在の検索キーワードをフォームへ渡します */}
<SearchForm defaultKeyword={keyword} />
<p>
検索キーワード:
<strong>{keyword === "" ? "未入力" : keyword}</strong>
</p>
{filteredProducts.length === 0 ? (
<p>該当する商品は見つかりませんでした。</p>
) : (
<ul>
{filteredProducts.map((product) => (
// 商品一覧を表示します
<li key={product.id}>
<h2>{product.name}</h2>
<p>{product.description}</p>
</li>
))}
</ul>
)}
</main>
);
}TSXこのコードで重要なのは、検索条件をURLから読むことと、検索結果をその値で決めることです。searchParams はページで使う検索条件向けの仕組みであり、Client Componentの useSearchParams はあくまでクライアント側で読むためのHookです。公式でも、ページデータの読み込みやフィルタリングにはPageの searchParams prop を使うことが勧められています。(🔗 nextjs.org)
Step 3:検索フォームをClient Componentで作る
次に、検索キーワードを入力してURLを更新するフォームを作ります。ここはブラウザー操作が必要なのでClient Componentにします。useRouter() はClient Component内でプログラム的にルート遷移するためのHookで、App Routerでは next/navigation から読み込みます。useSearchParams() は読み取り専用の URLSearchParams を返し、現在のクエリ文字列を参照できます。(🔗 nextjs.org)
src/app/products/SearchForm.tsx
// このファイルはClient Componentです
"use client";
// フォーム入力を管理するためにuseStateを使います
import { useState } from "react";
// URL操作に使うHookを読み込みます
import { usePathname, useRouter, useSearchParams } from "next/navigation";
// Propsの型です
type SearchFormProps = {
defaultKeyword: string;
};
// 検索フォームです
export default function SearchForm({
defaultKeyword,
}: SearchFormProps) {
// 入力欄の値を管理します
const [keyword, setKeyword] = useState(defaultKeyword);
// 現在のURL情報を取得します
const router = useRouter();
const pathname = usePathname();
const searchParams = useSearchParams();
// フォーム送信時の処理です
function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
// 通常のフォーム送信を止めます
event.preventDefault();
// 現在の検索パラメータを複製します
const params = new URLSearchParams(searchParams.toString());
// 前後の空白を取り除きます
const trimmedKeyword = keyword.trim();
// キーワードが空ならURLから削除します
if (trimmedKeyword === "") {
params.delete("keyword");
} else {
// キーワードがあるならURLへ設定します
params.set("keyword", trimmedKeyword);
}
// 新しいURLへ移動します
router.push(`${pathname}?${params.toString()}`);
}
return (
<form onSubmit={handleSubmit}>
<input
type="text"
value={keyword}
placeholder="キーワードを入力してください"
// 入力値をstateへ保存します
onChange={(event) => setKeyword(event.target.value)}
/>
<button type="submit">検索</button>
</form>
);
}TSXこの実装の考え方はとても大切です。useSearchParams() は読み取り専用なので、そのまま書き換えるのではなく、new URLSearchParams(searchParams.toString()) で新しいものを作ってから更新します。Next.js公式でも、現在の検索条件を複製し、set() で値を変更してから router.push() や Link で遷移する例が紹介されています。(🔗 nextjs.org)
Step 4:なぜServer Component側で絞り込むのか
ここは初心者が迷いやすいポイントです。検索フォームはClient Componentですが、一覧の絞り込みはServer Componentのページ側で行っています。これは、検索条件を使ってページデータを決める処理はPageの searchParams prop で行うのが基本だからです。公式ドキュメントでも、データベースのフィルタリングやページ読み込みに関わる検索条件には searchParams prop を使い、Client側だけで使う値には useSearchParams を使うと整理されています。(🔗 nextjs.org)
つまり、役割は次のように分けると分かりやすいです。
- 入力するのはClient Componentです。
- URLを書き換えるのもClient Componentです。
- そのURLをもとに一覧を決めるのはServer Componentです。
この設計にしておくと、あとで本物のデータベース検索や外部API検索へ発展させやすくなります。
Step 5:/products?keyword=react がどう動くのかを追いかける
ここで、実際の流れを頭の中で整理します。
- 利用者が検索欄に `react` と入力します。
- 送信すると、Client Componentが `router.push(“/products?keyword=react”)` を実行します。`useRouter()` はClient Componentでプログラム的なナビゲーションを行うためのHookです。
- Next.jsがそのURLへ遷移します。
- ページの `searchParams` に `keyword=react` が渡されます。ページは `searchParams` prop を受け取れます。
- Server Component側で商品一覧を `react` で絞り込みます。
- 絞り込まれた結果が表示されます。
この流れが理解できると、検索だけでなく、並び替え、絞り込み、ページネーションにも応用できます。
Step 6:検索条件を消したときの設計も重要
検索機能では、「入力したとき」だけでなく「消したとき」も大切です。今回のコードでは、キーワードが空文字なら params.delete("keyword") を使っています。これにより、/products?keyword= のような中途半端なURLではなく、/products に近い自然な形へ戻しやすくなります。
// キーワードが空ならURLから削除します
if (trimmedKeyword === "") {
params.delete("keyword");
} else {
// キーワードがあるならURLへ設定します
params.set("keyword", trimmedKeyword);
}TSXこのようにしておくと、URLが読みやすくなり、検索条件がない状態も扱いやすくなります。
Step 7:router.push と router.replace の違いも知っておく
今回の例では router.push() を使いました。useRouter() の push は新しい履歴を追加し、replace は履歴を追加せず現在の履歴を置き換えます。どちらもClient Componentで使えます。(🔗 nextjs.org)
検索機能では、次のように考えると分かりやすいです。
- 検索のたびに履歴を残したいなら `push` を使います。
- 細かい入力変更で履歴を増やしすぎたくないなら `replace` を使います。
たとえばリアルタイム検索では replace のほうが向くことが多いですが、今回は「送信して検索する」学習用なので push で十分です。
Step 8:部分一致検索をどう実装しているか
今回の検索は、includes() を使った部分一致検索です。さらに、検索時は大文字・小文字の違いで結果が変わりにくいように、小文字へそろえています。
// 比較しやすいように小文字へ変換します
const normalizedKeyword = keyword.trim().toLowerCase();
// 商品名と説明文をまとめて小文字化します
const targetText =
`${product.name} ${product.description}`.toLowerCase();
// キーワードが含まれているか確認します
return normalizedKeyword === ""
? true
: targetText.includes(normalizedKeyword);TSXこのように、検索条件と対象文字列の両方を同じ形にそろえて比較すると、初心者でも安定した検索を作りやすくなります。
Step 9:検索結果が0件のときも必ず考える
検索機能では、結果がある場合だけでなく、見つからない場合の表示も重要です。今回のコードでは、filteredProducts.length === 0 のときに専用メッセージを出しています。
{filteredProducts.length === 0 ? (
<p>該当する商品は見つかりませんでした。</p>
) : (
<ul>
{filteredProducts.map((product) => (
<li key={product.id}>
<h2>{product.name}</h2>
<p>{product.description}</p>
</li>
))}
</ul>
)}TSXこの処理がないと、利用者には「何も表示されないだけ」に見えてしまいます。検索機能では、失敗ではなく「該当なし」も普通の状態として丁寧に扱うことが大切です。
Step 10:実務で特に大事な注意点
検索機能は簡単そうに見えますが、実務では注意点があります。
- URLパラメータは利用者が自由に変更できるので、受け取った値をそのまま信用しないことが大切です。
- 空文字、長すぎる文字列、想定外の値も来る前提で考えます。
- 表示用の検索と、データベース問い合わせ用の検索は分けて考えるべきです。
今回の例は配列フィルタなので比較的安全ですが、将来データベース検索へつなぐなら、検索文字列の長さ制限、サニタイズ、バリデーション、必要に応じたレート制限も重要になります。URLパラメータは、フォーム入力と同じく「外部から来る値」として扱う癖をつけると安全です。
Step 11:リアルタイム検索に発展させる考え方
今回は送信ボタン付きの検索フォームでしたが、発展として「入力するたびにURLを更新して検索する」こともできます。その場合も、URL操作には useRouter()、現在値の確認には useSearchParams() が使えます。useSearchParams() はClient Component Hookで、現在のクエリ文字列を読むためのものです。(🔗 nextjs.org)
ただし、初心者向けにはまず送信型の検索をおすすめします。理由は、次の3つです。
- 処理の流れを追いやすいです。
- URLの変化を理解しやすいです。
- 不要な再検索を減らしやすいです。
Step 12:初心者向けテンプレート
最後に、最小テンプレートを載せておきます。
検索ページの最小テンプレート
// searchParamsを受け取るページです
export default async function Page({
searchParams,
}: {
// 現在の検索条件を受け取ります
searchParams: Promise<{ keyword?: string }>;
}) {
// URLからkeywordを取り出します
const { keyword = "" } = await searchParams;
return (
<main>
<h1>検索ページ</h1>
<p>現在のキーワード: {keyword}</p>
</main>
);
}TSX検索フォームの最小テンプレート
// Client Componentとして使います
"use client";
// 必要なHookを読み込みます
import { useState } from "react";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
// 検索フォームです
export default function SearchForm() {
// 入力値を管理します
const [keyword, setKeyword] = useState("");
// URL操作用のHookです
const router = useRouter();
const pathname = usePathname();
const searchParams = useSearchParams();
// フォーム送信時の処理です
function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
// 通常送信を止めます
event.preventDefault();
// 現在の検索条件を複製します
const params = new URLSearchParams(searchParams.toString());
// キーワードを設定します
params.set("keyword", keyword);
// URLを更新します
router.push(`${pathname}?${params.toString()}`);
}
return (
<form onSubmit={handleSubmit}>
<input
type="text"
value={keyword}
onChange={(event) => setKeyword(event.target.value)}
/>
<button type="submit">検索</button>
</form>
);
}TSXDay 47のチェックリスト
- URLパラメータを使った検索の基本が説明できます。
- ページで `searchParams` を受け取り、検索条件を読めます。`searchParams` はPageで使うための仕組みです。
- Client Componentで `useSearchParams()` を使って現在の検索条件を読めます。`useSearchParams` は読み取り専用です。
- `useRouter()` でURLを書き換えられます。`useRouter` はClient Componentでのプログラム的な遷移に使います。
- `/products?keyword=react` のようなURLで商品一覧を絞り込めます。
- 検索結果が0件のときの表示も実装できます。
- URLパラメータを外部入力として扱う意識を持てます。
まとめ
Day 47では、Next.js App RouterでURLパラメータを使った検索機能を作りました。検索条件はURLのクエリ文字列に持たせ、Server Componentのページでは searchParams prop でその値を受け取り、Client Componentのフォームでは useSearchParams、usePathname、useRouter を使ってURLを更新する、という流れが基本です。公式でも、ページのデータ読み込みに関わる検索条件は searchParams prop を使い、クライアント専用の読み取りには useSearchParams を使う形が案内されています。(🔗 nextjs.org)
この仕組みが理解できると、検索だけでなく、並び替え、カテゴリーフィルター、ページネーションにも発展させやすくなります。つまりDay 47は、ただの検索機能ではなく、URLと画面状態を一致させるNext.jsらしい設計を学ぶ回でもあります。
