2026年01月09日

Reactでクエリパラメーターのハンドリングを簡単にするライブラリ、nuqsを使ってみた

システム開発, レポート, React, nuqs

author | yuya.motozono

Reactでクエリパラメーターのハンドリングを簡単にするライブラリ、nuqsを使ってみた

はじめに

Reactでフロントエンド開発を行う際に、開発者の頭を悩ませる問題。

実務でReactを使っている方であれば、様々なものが頭の中に浮かぶかと思います。その中でも今回取り上げるのは、「クエリパラメーターのハンドリング」 です。

例えば、ユーザー間でECサイトのお気に入りの検索条件を保存・共有できるようにしたい、ブラウザの戻るボタン・進むボタンをクリックした際に、検索がリセットされないようにしたいなどの要件があるとします。

そのような場合には、URLのクエリパラメーターに条件を反映するような実装をすることで、上記のような機能を実現することができます。しかし、条件が増えれば増えるほど、一度に扱うパラメーター数は増加し、実装も煩雑で大変なものになってしまいます。

本記事では、そんなクエリパラメーターのハンドリングをラクに実装することができる便利なReactライブラリ「nuqs」をご紹介します。

nuqsについて

公式ドキュメントを見ると、Type-safe search params state manager for React と記載されています。

その名の通り、nuqsを使用すれば、クエリパラメーターの状態管理を型安全に行うことができます。

nuqsは、プレーンなReactはもちろん、Next.jsやRemixなど、React関連のフレームワークにも対応しています。Reactを使っているフロントエンドプロジェクトであれば、幅広く導入できるライブラリです。

実装はどれだけラクになる？

それでは、実際にnuqsを使用して実装してみます。どれくらいクエリパラメーターのハンドリングがラクになるのか、以下のようなデータ検索画面の実装を例にしてお伝えします。

下記のような動作となるよう、Claude Codeに実装してもらいました。

画面上部の各テキストボックスに値を入力すると、該当する項目の入力した条件に合致したデータが一覧として表示される
各テキストボックスに入力した値は、クエリパラメーターとしてURLに反映される

上記のような仕様をnuqsを使わずに実装すると下記のような処理になります（2の処理を行っている部分を抜粋）。

// 入力した値をクエリパラメーターとしてURLに反映する
const useQueryStringState = (key: string, initialValue: string | number | null) => {
  const location = useLocation();
  const navigate = useNavigate();
  const [value, setValue] = useState(() => {
    const params = new URLSearchParams(location.search);
    const paramValue = params.get(key);
    if (paramValue === null) {
      return initialValue;
    }
    if (typeof initialValue === 'number') {
      const num = Number(paramValue);
      return isNaN(num) ? initialValue : num;
    }
    return paramValue;
  });

  const updateUrl = useCallback(
    (newValue: string | number | null) => {
      const params = new URLSearchParams(location.search);
      if (newValue === null || newValue === '') {
        params.delete(key);
      } else {
        params.set(key, String(newValue));
      }
      navigate(`${location.pathname}?${params.toString()}`, { replace: true });
    },
    [key, location.pathname, location.search, navigate]
  );

  const setStateValue = (newValue: string | number | null) => {
    setValue(newValue);
    updateUrl(newValue);
  };

  return [value, setStateValue] as const;
};

useLocationやuseNavigate、useState、URLSearchParams...と複数のHooksやWeb APIがふんだんに使われていますね。
文字列のデータと数値のデータがありますが、URLSearchParamsはすべて文字列で値を返すため、数値への変換やバリデーションが必要になり、型のハンドリングが煩雑になってしまいます。

ファイル全体の行数は226行でした。

続いて、nuqsを使った実装です（2の処理を行っている部分を抜粋）。

// 入力した値をクエリパラメーターとしてURLに反映する
const [filters, setFilters] = useQueryStates({
    region: parseAsString.withDefault(''),
    industry: parseAsString.withDefault(''),
    businessActivitySales: parseAsInteger,
    establishmentSales: parseAsInteger,
    totalEmployees: parseAsInteger,
    dispatchers: parseAsInteger,
    recipients: parseAsInteger,
    workers: parseAsInteger,
});