ReactでSVGスプライトを使い、アイコンをまとめる方法
アイコンの SVG を <symbol> に入れて1つのファイルにまとめておくと、React のコンポーネントからは <use href="/icons.svg#icon-home"> の1行で呼び出せます。検証用の画面に19個置いたときも、スプライトのファイルの読み込みは1回でした。色は親の color で変わり、大きさは外側の <svg> の width と height で決まります。
私は、アイコンの SVG ファイルからスプライトと名前の型を作るスクリプトと、Icon というコンポーネントを書き、Chromium で表示を確かめました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、Chromium 153 です。使ったのは React 19.3.1、TypeScript 7.0.2、esbuild 0.28.2、Playwright 1.63.0 です。.tsx を tsc で型チェックしてから esbuild で変換し、Playwright で Chromium を操作して、画素の色やアクセシビリティツリーを確かめました。Firefox と Safari、スマートフォンのブラウザ、スクリーンリーダーでの読み上げは試していません。Vite などのバンドラーの SVG 用プラグインも扱っていません。

アイコンを symbol にまとめたスプライトを作る
元にするのは、1つのアイコンを1つのファイルにした、ふつうの SVG です。家のアイコンは次のとおりです。
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M3 11 12 3l9 8"/>
<path d="M5 10v10h14V10"/>
<path d="M10 20v-6h4v6"/>
</svg>
これを icons/ に置いておき、次のスクリプトで1つのファイルにまとめます。ファイルごとに <svg> を <symbol> に置き換え、ファイル名から icon-home のような id を付けます。viewBox や stroke などの属性は、そのまま <symbol> に移します。中に <defs> や id を持たない、単純なアイコンを前提にした書き方です。
// icons/*.svg を1つのスプライト(public/icons.svg)にまとめ、名前の型(src/icon-names.ts)を書き出す
import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
const files = readdirSync('icons').filter((f) => f.endsWith('.svg')).sort();
const names = [];
const symbols = files.map((file) => {
const name = file.replace(/\.svg$/, '');
const svg = readFileSync(`icons/${file}`, 'utf8');
const [, attrs, body] = svg.match(/<svg([^>]*)>([\s\S]*?)<\/svg>/);
// xmlns 以外の属性(viewBox、fill、stroke など)は、そのまま symbol に移す
const kept = attrs.replace(/\s+xmlns="[^"]*"/, '');
names.push(name);
return ` <symbol id="icon-${name}"${kept}>${body.trim().replace(/\s*\n\s*/g, '')}</symbol>`;
});
writeFileSync(
'public/icons.svg',
`<svg xmlns="http://www.w3.org/2000/svg">\n${symbols.join('\n')}\n</svg>\n`,
);
writeFileSync(
'src/icon-names.ts',
`// scripts/build-sprite.mjs が書き出すファイル。手で編集しない\n` +
`export const iconNames = ${JSON.stringify(names)} as const;\n` +
`export type IconName = (typeof iconNames)[number];\n`,
);
console.log(`${names.length} icons: ${names.join(', ')}`);
5つのアイコンで実行すると、public/icons.svg は次のようになりました(家と検索の2つだけ載せています)。
<svg xmlns="http://www.w3.org/2000/svg">
<symbol id="icon-home" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 11 12 3l9 8"/><path d="M5 10v10h14V10"/><path d="M10 20v-6h4v6"/></symbol>
<symbol id="icon-search" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="10.5" cy="10.5" r="6.5"/><path d="m15.5 15.5 5 5"/></symbol>
</svg>
MDN の symbol の説明にあるとおり、<symbol> はそれだけでは描かれず、<use> から参照されたところにだけ描かれます。スプライトのファイルに並べておくだけなら、何も表示されません。
同時に書き出す src/icon-names.ts は、アイコンの名前の一覧と、その型です。
// scripts/build-sprite.mjs が書き出すファイル。手で編集しない
export const iconNames = ["heart","home","mail","search","wide"] as const;
export type IconName = (typeof iconNames)[number];
use で呼び出す Icon コンポーネント
コンポーネントは、外側の <svg> の中に <use> を1つ置くだけです。
import type { IconName } from './icon-names';
// スプライトの URL。ページと同じオリジンから配信する
const SPRITE_URL = '/icons.svg';
type Props = {
name: IconName;
size?: number;
// 渡したときだけ、画像として読み上げられる名前になる
label?: string;
className?: string;
};
export function Icon({ name, size = 24, label, className }: Props) {
return (
<svg
width={size}
height={size}
className={className}
role={label ? 'img' : undefined}
aria-label={label}
aria-hidden={label ? undefined : true}
>
<use href={`${SPRITE_URL}#icon-${name}`} />
</svg>
);
}
href には「ファイルの URL + # + symbol の id」を渡します。MDN の use の説明によると、以前使われていた xlink:href は SVG 2 で非推奨になり、href に置き換わりました。React でも href と書けば、そのまま <use> の href 属性になります。
使う側では、名前と大きさを渡します。
<button type="button" className="btn">
<Icon name="home" size={20} />
ホーム
</button>
検証用の画面には、この Icon を19個置きました。Playwright でリクエストを数えると、icons.svg へのリクエストは1回だけでした。
name の型を IconName にしているので、スプライトにない名前は型チェックで止まります。<Icon name="serch" /> と書くと、tsc は次のエラーを出しました。
src/typo.tsx(3,33): error TS2820: Type '"serch"' is not assignable to type '"heart" | "home" | "mail" | "search" | "wide"'. Did you mean '"search"'?
型がないと、この間違いは画面を見るまで分かりません。href の id を存在しない icon-nothing に書き換えると、アイコンの場所には何も描かれず(色の付いた画素は 0)、コンソールにもエラーは出ませんでした。
大きさは外側の svg、色は親の color で変える
<use> には width と height を付けず、外側の <svg> の width と height だけを変えて試しました。viewBox が 0 0 24 24 の家のアイコンに、size で 16、24、48 を渡すと、それぞれの大きさに拡大・縮小されて描かれました(冒頭の画像の「大きさを変える」)。
色は、アイコンの線を stroke="currentColor" で描いておき、使う側の color で決めます。MDN の color の値の説明にあるとおり、currentColor はその要素の color の値を指します。封筒のアイコンを、color を #1f2a30、#00c8e8、#d85878 にした要素の中に置くと、どれも色の付いた画素は 710 で、いちばん多い色はそれぞれ指定した色でした。ボタンの中のアイコンが、ボタンの文字と同じ白や濃い灰色になっているのも、この仕組みによるものです。
縦横比が 2:1 の矢印(viewBox="0 0 48 24")を、正方形の <svg> に入れると、上下に余白ができました。48×48 で描くと、線が描かれたのは y が 16〜31 の範囲で、上下の真ん中に寄っていました。MDN の preserveAspectRatio の説明によると、何も指定しないときは xMidYMid meet で、縦横比を保ったまま枠に収まる大きさにし、真ん中にそろえます。height を 24 にすると、y が 4〜19 の範囲に描かれ、余白はなくなりました。

この記事の Icon は、size 1つで幅と高さに同じ値を入れているので、横長のアイコンを使うときは、width と height を別々に渡せるようにする必要があります。
中の塗りは、外からのセレクターでは変わらない
ハートのアイコンで、「お気に入り」になったときだけ中を塗りたいとします。<use> で描いた中身は、ページの DOM からは見えない場所に複製されます。MDN の use の説明には、複製された要素に CSS を当てるときは注意が要り、明示的に継承させないと、プロパティが受け継がれる保証はないと書かれています。
試しに、ページの CSS に .by-selector path { fill: #00c8e8; } と書き、外側の <svg> に付けたクラスを起点に、中の path を指定しました。この指定は効かず、塗られた画素の数(473)も、いちばん多い色(#d85878)も、何も指定しないハートと同じでした。
そこで、スプライトの側で、塗りを CSS のカスタムプロパティから受け取るようにしました。
<symbol id="icon-heart" viewBox="0 0 24 24"><path style="fill: var(--icon-accent, none)" stroke="currentColor" stroke-width="2" stroke-linejoin="round" d="M12 20s-7.5-4.6-7.5-10A4.3 4.3 0 0 1 12 7.4 4.3 4.3 0 0 1 19.5 10c0 5.4-7.5 10-7.5 10Z"/></symbol>
使う側では、外側の <svg> に --icon-accent を指定するだけです。
.like { color: #d85878; }
.like.on { --icon-accent: #d85878; }
MDN のカスタムプロパティの説明にあるとおり、カスタムプロパティは親から値を受け継ぎます。.like.on のハートは、塗られた画素が 473 から 849 に増え、中までピンクになりました。--icon-accent を指定しないハートでは、MDN の var() の説明にある代わりの値として、2つめに書いた none が使われ、輪郭だけになります。
<use> で描いたアイコンの中は、外からのセレクターでは選べません。色を変えたい場所は、スプライトの側で currentColor やカスタムプロパティを使って書いておき、使う側は color やカスタムプロパティで値を渡します。
読み上げる名前は、使う場所で付ける
Icon は、label を渡さなければ aria-hidden を付け、読み上げの対象から外します。ボタンのように、すぐ横に文字がある場所では、アイコンが読まれる必要はないからです。
アイコンだけのボタンには、ボタン自身に aria-label を付けます。
<button type="button" className="btn icon-only" aria-label="検索">
<Icon name="search" size={20} />
</button>
アイコンそのものに意味があるときは、label を渡して role="img" と aria-label を付けます。
<Icon name="heart" size={20} label="お気に入り" className="like on" /> 3件
Chromium のアクセシビリティツリーでは、ボタンは「ホーム」「送信」「検索」という名前になり、ハートは「お気に入り」という名前の画像(img)になっていました。aria-hidden を付けた大きさや色の見本のアイコンは、ツリーに出てきませんでした。
スプライトは、ページと同じオリジンから配信する
スプライトのファイルは、ページと同じオリジン(スキーム、ホスト名、ポートがすべて同じ場所)から配信します。
ページを http://localhost:3000/ で開き、<use> の href を、ホスト名とポート番号の違う http://127.0.0.1:3001/icons.svg#icon-mail に書き換えました。ファイルへのリクエストは送られましたが、アイコンは描かれず(色の付いた画素は 0)、コンソールに次のエラーが出ました。
error: Unsafe attempt to load URL http://127.0.0.1:3001/icons.svg from frame with URL http://localhost:3000/. Domains, protocols and ports must match.
レスポンスに Access-Control-Allow-Origin: * を付けたサーバー(http://127.0.0.1:3002/)から読み込んでも、検証環境の Chromium では同じく表示されませんでした。MDN の use の説明にも、ブラウザは <use> に同一オリジンポリシーを当てて、別オリジンの URL の読み込みを拒むことがあり、<use> に別オリジンからの読み込みを許す決まった方法は今のところない、と書かれています。





