2026年9月10日

WordPressでSVGアイコンセットを管理画面からアップロードして使う方法（安全な許可とスプライト化）

テーマ・デザイン

WordPress で SVG アイコンセットを管理画面から扱うには、まずサニタイズ機能のあるプラグイン（Safe SVG など）で SVG のアップロードを安全に許可し、次にアイコンを1つのスプライトファイルにまとめてメディアライブラリに置き、ショートコードなどから <use> で呼び出すのが扱いやすい方法です。こうすると、アイコンの追加や差し替えは管理画面のアップロードだけで済み、色は CSS で文字色に合わせて変えられます。この記事では、SVG が標準で許可されていない理由、アップロードの許可、スプライトの作り方、記事やテーマでの呼び出し方、アクセシビリティとつまずきやすい点を説明します。

SVG が標準でアップロードできない理由

WordPress の標準設定では、メディアライブラリに SVG をアップロードしようとすると「このファイル形式はセキュリティ上の理由から許可されていません」といった旨のエラーになります（2026年10月現在）。

理由は、SVG が画像であると同時に XML の文書であり、中に <script> 要素や onload などのイベント属性、外部リソースへの参照を含められるからです。悪意のある SVG がアップロードされ、その URL を直接開くと、サイトのドメイン上でスクリプトが動く（クロスサイトスクリプティング）おそれがあります。複数人で運用しているサイトでは、投稿者権限のアカウントが乗っ取られた場合にも同じ問題が起こり得ます。

そのため、upload_mimes フィルターで svg を許可するだけのコードは勧められません。許可するなら「中身を無害化（サニタイズ）してから保存する」ことと「誰がアップロードできるかを絞る」ことをセットで考えます。

SVG のアップロードを安全に許可する

自分でサニタイズ処理を書くより、実績のあるプラグインを使うほうが安全です。代表的なのは次の2つです。

Safe SVG（10up）: アップロード時に SVG をサニタイズし、スクリプトや危険な属性を取り除きます。メディアライブラリでのプレビュー表示にも対応しています。
SVG Support: SVG のアップロードを許可し、設定でアップロードできる権限を管理者に限定したり、サニタイズを有効にしたりできます。

どちらも機能や設定画面の表記はバージョンによって変わるため、導入時にプラグインの説明ページで「サニタイズの有無」と「アップロードできるユーザーを制限できるか」を確認してください。可能であれば、SVG をアップロードできるのは管理者だけにしておくと安心です。

プラグインの追加は、本番の前にステージング環境で試し、バックアップを取ってから行ってください。

アイコンセットをスプライトにまとめる

アイコンを1つずつアップロードして画像ブロックで貼る方法もありますが、<img> で表示した SVG は CSS で色を変えられません。ボタンの文字色に合わせてアイコンの色も変えたい、ホバーで色を変えたい、といった用途では、複数のアイコンを <symbol> でまとめたスプライトファイルを使うのが向いています。

<svg xmlns="http://www.w3.org/2000/svg">
  <symbol id="icon-check" viewBox="0 0 24 24">
    <path d="M9 16.2 4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z"/>
  </symbol>
  <symbol id="icon-arrow-right" viewBox="0 0 24 24">
    <path d="M12 4l-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z"/>
  </symbol>
</svg>

作るときのポイントは次のとおりです。

id は小文字・英数字・ハイフンで統一する: 後で紹介するショートコードは名前を小文字に正規化するため、icon-Arrow のような大文字を含む id は呼び出せません。
viewBox を残す: 拡大縮小の基準になるため、各 symbol に元のアイコンの viewBox を付けます。
fill を書かない、または currentColor にする: パスに fill="#333" のような固定色が入っていると、CSS で色を変えられません。アイコン素材から書き出した SVG には固定色が入っていることが多いので、取り除いておきます。
ライセンスを確認する: 配布されているアイコンセットは、それぞれ利用条件が異なります。商用利用やクレジット表記の要否を確認してから使ってください。

アイコンが多い場合は、SVGO などのツールで不要なメタデータを削ってからまとめるとファイルが軽くなります。

メディアライブラリにアップロードして確認する

スプライトファイル（例: icons.svg）を「メディア」→「新規追加」からアップロードします。アップロードできたら、次の2点を確認します。

添付ファイルの ID: メディアの編集画面の URL に含まれる post=123 の数字が添付ファイル ID です。次の手順で使います。
サニタイズ後の中身: 添付ファイルの URL をブラウザーで開くか、ダウンロードしてテキストエディターで開き、symbol 要素と id が残っているかを見ます。サニタイズの設定によっては、要素や属性が取り除かれることがあります。

アイコンを追加・変更したいときは、スプライトを作り直して同じ添付ファイルを差し替えるか、新しくアップロードして ID を書き換えます。ブラウザーやページキャッシュに古いファイルが残ることがあるので、差し替え後はキャッシュの削除も行ってください。

ショートコードでアイコンを呼び出す

記事やウィジェットから使えるよう、ショートコードを用意します。テーマを変えても使えるよう、wp-content/mu-plugins/ に置くプラグインとして作るのがおすすめです。子テーマの functions.php に書いても動きます。

<?php
/**
 * Plugin Name: My SVG Icons
 * Description: メディアライブラリのSVGスプライトからアイコンを表示するショートコード
 */

// メディアライブラリにアップロードしたスプライトの添付ファイルID
const MY_ICONS_SPRITE_ID = 123;

add_shortcode( 'icon', function ( $atts ) {
	$atts = shortcode_atts(
		array(
			'name'  => '',
			'label' => '',
			'size'  => '24',
		),
		$atts,
		'icon'
	);

	$name = sanitize_key( $atts['name'] );
	if ( '' === $name ) {
		return '';
	}

	$url = wp_get_attachment_url( MY_ICONS_SPRITE_ID );
	if ( ! $url ) {
		return '';
	}

	$size  = absint( $atts['size'] ) ?: 24;
	$label = sanitize_text_field( $atts['label'] );

	// 意味を持つアイコンは名前を付け、装飾だけのアイコンは読み上げ対象から外す
	$a11y = ( '' !== $label )
		? 'role="img" aria-label="' . esc_attr( $label ) . '"'
		: 'aria-hidden="true" focusable="false"';

	return sprintf(
		'<svg class="icon icon-%1$s" width="%2$d" height="%2$d" %3$s><use href="%4$s"></use></svg>',
		esc_attr( $name ),
		$size,
		$a11y,
		esc_url( $url . '#icon-' . $name )
	);
} );

記事ではショートコードブロックなどに [icon name="check"]、意味を持たせたい場合は [icon name="arrow-right" label="次へ"] のように書きます。色と配置は CSS で整えます。

.icon {
	display: inline-block;
	fill: currentColor;
	vertical-align: middle;
}

fill: currentColor により、アイコンは周囲の文字色を引き継ぎます。リンクやボタンの中に置けば、ホバー時の色変化にも自動で追従します。

この方法の利点は、編集者が SVG のコードを直接貼らずに済むことです。WordPress は unfiltered_html 権限を持たないユーザーが投稿に書いた <svg> を除去するため、カスタム HTML ブロックに SVG を貼る運用は、権限によって表示されたりされなかったりと混乱の元になります。

つまずきやすい点

アイコンが表示されない（別ドメインの場合）: <use> で外部ファイルを参照できるのは、原則として同じオリジンのファイルだけです。メディアを CDN や外部ストレージに転送するプラグインを使っていると、スプライトの URL が別ドメインになり表示されません。その場合は、スプライトだけ同じドメインに置くか、テーマ内にファイルを置いてページ内にインラインで出力する方式に切り替えます。
色が変わらない: スプライト内のパスに固定の fill や style が残っていないかを確認します。
大きさがおかしい: symbol に viewBox があるか、CSS で width や height を上書きしていないかを確認します。
画像ブロックに挿入した SVG が表示されない、または巨大になる: SVG に width・height 属性がないと、表示サイズが決まらないことがあります。画像ブロック側で幅を指定するか、ファイルに属性を付けます。

ブロックエディターでアイコンを選んで挿入したい場合は、The Icon Block のようなアイコン用ブロックを追加するプラグインもあります。Font Awesome を使うなら公式プラグインもありますが、読み込むアイコン数が多いと表示速度に影響するため、使うアイコンだけを SVG スプライトにする方法と比較して選んでください。

まとめ

SVG はスクリプトを含められるため、WordPress の標準では許可されていない。upload_mimes で許可するだけの方法は避ける。
Safe SVG など、サニタイズ機能のあるプラグインで許可し、アップロードできるユーザーを絞る。
アイコンセットは <symbol> でスプライトにまとめ、固定色を取り除いて currentColor で色を付けられるようにする。
メディアライブラリにアップロードしたスプライトを、エスケープ処理を入れたショートコードから <use> で呼び出す。
装飾アイコンは aria-hidden="true"、意味を持つアイコンには名前を付ける。CDN 転送で別ドメインになると表示されない点に注意する。