ReactとURLPatternでURLから値を取り出す方法
/items/42 の 42 や、/tags/猫 の「猫」のように、URL のパスに入った値を取り出したいときは、ブラウザ標準の URLPattern が使えます。/items/:id のような形を書いておくと、exec() が { id: '42' } を返します。
商品の詳細ページや記事のページのように、URL によって表示を切り替えたいけれど、ルーターのライブラリを入れるほどではない小さなアプリで、URLPattern は役に立ちます。ここでは、URL から「どの画面か」と「その画面で使う値」を取り出す関数を作り、React の表示につなげました。
検証環境は Ubuntu 24.04、Node.js 22.23.4 です。react / react-dom 19.3.1、@types/react 19.3.0、typescript 7.0.2、esbuild 0.28.2 を使い、.tsx を tsc で型チェックしてから esbuild の開発用ビルドで変換しました。ブラウザは Playwright 1.63.0 で動かした Chromium 153(ヘッドレス)だけです。Firefox、Safari、サーバーサイドレンダリング、React Router などのルーターとの組み合わせ、ブラウザで polyfill を読み込む使い方は試していません。
どのブラウザで使えるか
MDN の互換性データでは、URLPattern は Chrome と Edge がバージョン95から、Firefox が142から、Safari が26から対応しています。Node.js は24からです。
型は TypeScript の DOM の型定義に入っています。検証環境の TypeScript 7.0.2 では、"lib": ["ES2022", "DOM"] のままで new URLPattern() と exec() の結果の型チェックが通りました。
exec() でパスの値を取り出す
URLPattern には、URL のどの部分をどんな形で照合するかを渡します。パスだけを決めたいときは pathname を渡します。:id のように : で始まる部分が、名前付きのグループです。
const p = new URLPattern({ pathname: '/items/:id' });
p.test('https://example.com/items/3'); // true
p.exec('https://example.com/items/3')?.pathname.groups; // { id: '3' }
exec() は、合わなければ null を、合えば URL の部分ごとの結果を返します(MDN の exec() の説明)。パスの値は pathname.groups に入っています。検証環境の Chromium で、いくつかの URL を試した結果は次のとおりです。
| 照合した URL | pathname.groups |
|---|---|
https://example.com/items/3 |
{ id: '3' } |
https://example.com/items/3?tab=a#x |
{ id: '3' } |
https://example.com/items/3/ |
合わない(null) |
https://example.com/items/ |
合わない(null) |
https://example.com/items/猫 |
{ id: '%E7%8C%AB' } |
取り出した値には、気をつけることが3つあります。
1つ目は、値がいつも文字列であることです。/items/:id(\\d+) と数字だけに絞っても、typeof は 'string' でした。数として使うなら Number() で変換します。
2つ目は、日本語などの文字が、パーセントエンコードされたまま返ることです。/items/猫 を渡しても %E7%8C%AB が返りました。画面に出すときは decodeURIComponent() で「猫」に戻します。
3つ目は、末尾のスラッシュです。/items/:id は /items/3/ に合いません。MDN の URL Pattern API の説明にあるとおり、{/}? を末尾に付けると、スラッシュがあってもなくても合います。検証環境でも、/items/:id{/}? は /items/3 と /items/3/ の両方で { id: '3' } を返しました。
パターンの書き方で、合う URL を絞る
グループの後ろに ( ) で正規表現を書くと、合う値を絞れます(MDN のパターンの書き方の説明)。正規表現は文字列の中に書くので、\d はコードでは \\d と書きます。検証環境で試した結果は次のとおりです。
| パターン | 照合したパス | 結果 |
|---|---|---|
/items/:id(\\d+) |
/items/3 |
合う |
/items/:id(\\d+) |
/items/abc |
合わない |
/blog/:year/:month? |
/blog/2026 |
{ year: '2026' } |
/blog/:year/:month? |
/blog/2026/11 |
{ year: '2026', month: '11' } |
/files/:path+ |
/files/a/b |
{ path: 'a/b' } |
/docs/* |
/docs/a/b/c |
{ '0': 'a/b/c' } |
? を付けたグループは、なくても合います。/blog/2026 では、結果に month の値は入っていませんでした(groups.month を読むと undefined です)。+ を付けると、/ をまたいだ残りのパスをまとめて受け取れます。* も残りのパスを受け取りますが、名前がないので、キーは '0' になります。
大文字と小文字は区別されます。/items/:id は /Items/3 に合いませんでした。区別したくないときは、コンストラクターの ignoreCase オプションを使います。new URLPattern({ pathname: '/items/:id' }, { ignoreCase: true }) にすると、/Items/3 にも合いました。
クエリは URLSearchParams で読む
?q=cat のようなクエリも、URLPattern の search に書けます。ただし、{ pathname: '/search', search: 'q=:q' } で試したところ、次のようになりました。
| 照合した URL | search.groups |
|---|---|
https://example.com/search?q=cat |
{ q: 'cat' } |
https://example.com/search?q=cat&page=2 |
{ q: 'cat&page=2' } |
https://example.com/search?page=2&q=cat |
合わない(null) |
MDN にある、グループが合う文字の範囲の説明によると、グループが / 以外のすべての文字に合うのは pathname だけです。search では、グループはすべての文字に合います。そのため & から後ろまで q に入ってしまいます。クエリは書く順番が決まっていないので、search のパターンで照合するのにも向きません。
クエリの値は、new URL(href).searchParams.get('page') のように、URLSearchParams で読むのが確実です。順番に関係なく、page は '2'、q は 'cat' と取り出せました。
URL から画面と値を決める関数を作る
ここからは React で使う形にします。まず、URL の文字列を受け取って、「どの画面か」と「その画面で使う値」を返す関数 matchRoute を作ります。React に関係しない、ただの関数です。

// routes.ts
// URL から、どの画面か と その画面で使う値 を取り出す。
const itemPattern = new URLPattern({ pathname: '/items/:id(\\d+){/}?' });
const tagPattern = new URLPattern({ pathname: '/tags/:tag{/}?' });
export type Route =
| { name: 'item'; id: number }
| { name: 'tag'; tag: string; page: number }
| { name: 'notFound' };
export function matchRoute(href: string): Route {
const item = itemPattern.exec(href);
if (item) {
return { name: 'item', id: Number(item.pathname.groups.id) };
}
const tag = tagPattern.exec(href);
if (tag) {
const raw = tag.pathname.groups.tag ?? '';
let decoded: string;
try {
decoded = decodeURIComponent(raw);
} catch {
return { name: 'notFound' }; // %E7%8C のような壊れた値
}
// クエリは URLPattern ではなく URLSearchParams で読む
const page = Number(new URL(href).searchParams.get('page') ?? '1');
return { name: 'tag', tag: decoded, page: Number.isInteger(page) && page > 0 ? page : 1 };
}
return { name: 'notFound' };
}
パターンは、ファイルの一番上で一度だけ作っています。コンポーネントの中で作ると、描画のたびに作り直すことになるためです。
exec() の結果の groups の型は、値が string | undefined のオブジェクトです。そのままでは、id があることを型で保証できません。そこで、画面ごとに必要な値を持つ型 Route を返すようにしました。呼び出し側は route.name で分岐すれば、route.id を number として使えます。
decodeURIComponent() は、%E7%8C のように途中で切れた値を渡すと例外を投げます。検証環境でも URIError: URI malformed になりました。描画の途中で例外が起きないよう、try で受け止めて「見つからない」扱いにしました。
React で今の URL を読み、表示を切り替える
今の URL は、useSyncExternalStore で React の値として読みます。ブラウザの「戻る」「進む」では popstate イベントが起きるので、それを購読します。
// useLocationHref.ts
import { useSyncExternalStore } from 'react';
const NAVIGATE = 'app:navigate';
function subscribe(onChange: () => void) {
window.addEventListener('popstate', onChange);
window.addEventListener(NAVIGATE, onChange);
return () => {
window.removeEventListener('popstate', onChange);
window.removeEventListener(NAVIGATE, onChange);
};
}
// 今の URL(location.href)を React の値として読む
export function useLocationHref(): string {
return useSyncExternalStore(subscribe, () => window.location.href);
}
export function navigate(to: string) {
history.pushState(null, '', to);
// pushState では popstate が起きないので、自分で知らせる
window.dispatchEvent(new Event(NAVIGATE));
}
リンクを押したときは、history.pushState() で URL だけを変えます。MDN の popstate の説明にあるとおり、pushState() を呼んでも popstate は起きません。そこで、自分で決めた名前のイベント app:navigate を送っています。検証環境で、この dispatchEvent の行を消して「商品42」のリンクを押したところ、アドレスバーの URL は /items/42/ になったのに、画面は「商品 3 の詳細」のままでした。
コンポーネントでは、読んだ URL を matchRoute に渡して、表示を選びます。
// App.tsx
import type { MouseEvent, ReactNode } from 'react';
import { matchRoute } from './routes';
import { navigate, useLocationHref } from './useLocationHref';
function Link({ to, children }: { to: string; children: ReactNode }) {
const onClick = (e: MouseEvent<HTMLAnchorElement>) => {
if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
e.preventDefault();
navigate(to);
};
return <a href={to} onClick={onClick}>{children}</a>;
}
export function App() {
const href = useLocationHref();
const route = matchRoute(href);
return (
<main>
<nav>
<Link to="/items/3">商品3</Link> <Link to="/items/42/">商品42</Link>{' '}
<Link to="/tags/%E7%8C%AB?page=2">タグ「猫」の2ページ目</Link>{' '}
<Link to="/items/abc">商品abc</Link>
</nav>
<section>
{route.name === 'item' && <h1>商品 {route.id} の詳細</h1>}
{route.name === 'tag' && <h1>タグ「{route.tag}」の {route.page} ページ目</h1>}
{route.name === 'notFound' && <h1>ページが見つかりません</h1>}
</section>
</main>
);
}
Link は、左ボタン以外のクリックや、Ctrl キーなどを押しながらのクリックでは preventDefault() を呼ばず、ブラウザのふだんの動きに任せます。
検証用のサーバーは、どのパスを開かれても同じ HTML を返すようにしました。Playwright で URL を直接開いたときの表示は、次のとおりです(検証に使ったコードでは、確認のために id の型も表示しています)。
| 開いた URL | 表示 |
|---|---|
/items/3 |
商品 3 の詳細(id は number) |
/items/3/ |
商品 3 の詳細 |
/items/abc |
ページが見つかりません |
/tags/%E7%8C%AB?page=2 |
タグ「猫」の 2 ページ目 |
/tags/猫 |
タグ「猫」の 1 ページ目 |
/tags/%E7%8C%AB?page=abc |
タグ「猫」の 1 ページ目 |
/tags/%E7%8C |
ページが見つかりません |
/Items/3 |
ページが見つかりません |
/items/3 を開いてから、リンクで「タグ「猫」の2ページ目」「商品42」と移り、Playwright で履歴を2回戻り、1回進めました。どの時点でも、表示は URL と合っていました。この間、ページの読み込みは0回でした。
URLPattern がないブラウザでは、読み込む前に確かめる
対応していないブラウザでは、URLPattern という名前自体がありません。検証では、ページを開く前に window.URLPattern を消して、対応していないブラウザの代わりにしました。
最初は、main.tsx の先頭で App を import し、描画の前に 'URLPattern' in globalThis を確かめていました。この形では、画面に何も出ませんでした。ブラウザのコンソールには URLPattern is not defined というエラーが出ていました。routes.ts を読み込んだ時点で new URLPattern() が動くので、確かめる処理までたどり着かないためです。
そこで、確かめてから App を読み込むようにしました。
// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root')!);
if ('URLPattern' in globalThis) {
// routes.ts は読み込んだ時点で new URLPattern() を呼ぶので、確かめてから読み込む
import('./App').then(({ App }) => {
root.render(<StrictMode><App /></StrictMode>);
});
} else {
root.render(<p>このブラウザは URLPattern に対応していません</p>);
}
この形では、URLPattern を消したページに「このブラウザは URLPattern に対応していません」と表示されました。MDN の URLPattern のページでは、URLPattern の polyfill も紹介されています。
Node.js 22 で matchRoute をテストする
matchRoute は React に関係しない関数なので、Node.js のテストランナーでも確かめられます。ただし、Node.js 22 には URLPattern がありません。検証環境では typeof URLPattern が 'undefined' で、routes.ts を読み込むと ReferenceError: URLPattern is not defined になりました。
テストでは、urlpattern-polyfill 10.1.0 を先に読み込みました。この polyfill は、import 'urlpattern-polyfill' と書くと URLPattern を使えるようにします。
// routes.test.ts
import 'urlpattern-polyfill'; // Node.js 22 には URLPattern がない
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { matchRoute } from '../src/routes';
test('商品の id を数値で取り出す', () => {
assert.deepEqual(matchRoute('https://example.com/items/3/'), { name: 'item', id: 3 });
});
test('タグを日本語に戻し、ページ番号をクエリから読む', () => {
assert.deepEqual(matchRoute('https://example.com/tags/%E7%8C%AB?page=2'), { name: 'tag', tag: '猫', page: 2 });
});
test('数字でない id は見つからない扱い', () => {
assert.deepEqual(matchRoute('https://example.com/items/abc'), { name: 'notFound' });
});
esbuild で1つのファイルにまとめてから、node --test で動かしました。3件とも通りました。
$ npx esbuild test/routes.test.ts --bundle --platform=node --format=esm --outfile=dist/routes.test.mjs && node --test dist/routes.test.mjs
ok 1 - 商品の id を数値で取り出す
ok 2 - タグを日本語に戻し、ページ番号をクエリから読む
ok 3 - 数字でない id は見つからない扱い
# tests 3
# pass 3
# fail 0
型チェックでは1つ問題がありました。polyfill の型定義と TypeScript の DOM の型定義の両方に URLPattern があり、tsc が Duplicate identifier 'URLPattern' などのエラーを出しました。テスト用の tsconfig に "skipLibCheck": true を加えると、エラーは出なくなりました。
{ "extends": "./tsconfig.json", "compilerOptions": { "types": ["node"], "skipLibCheck": true }, "include": ["src", "test"] }





