カスタムブロックを作ってインサーター（ブロック挿入ツール）を開くと、自分のブロックだけが味気ない四角いアイコンで並んでいる——ということがあります。アイコンはブロックを見分けるための目印なので、内容に合ったものを設定しておくと使い勝手が一気に良くなります。
この記事では、block.json に Dashicons の名前を書く一番手軽な方法から、registerBlockType 側でオブジェクトを渡して色を付ける方法、独自の SVG をアイコンにする方法、そして @wordpress/icons パッケージのアイコンを使う方法までを順番に解説します。
目次
ブロックのアイコンが表示される場所
設定したアイコンは、インサーターの一覧だけでなく、リストビュー（ドキュメント概観）の各行、ブロックを選択したときのツールバー左端、設定サイドバーの上部に出るブロック名の横など、エディターのあちこちで使われます。つまり「一度決めたら編集画面全体で繰り返し目に入るもの」なので、内容が想像しやすい図柄を選ぶことが大切です。
アイコンを指定しなかった場合は、WordPress が用意しているデフォルトのブロックアイコン（四角い図形）が使われます。動作上の問題はありませんが、自作ブロックが複数あると区別が付かなくなるので、必ず設定しておきたい項目です。
block.json に Dashicons の名前を書く
もっとも手軽なのが、block.json の icon プロパティに Dashicons のスラッグ（名前）を文字列で書く方法です。Dashicons は WordPress 本体に同梱されているアイコンフォントで、管理画面のメニューなどで昔から使われています。
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "webool/notice-box",
"title": "お知らせボックス",
"category": "design",
"icon": "smiley",
"editorScript": "file:./index.js"
}ここで書くのは smiley や megaphone のようなスラッグだけです。CSS クラスとして使うときの dashicons-smiley という形ではないので、dashicons- の部分は付けません。使えるスラッグの一覧は、記事末尾に挙げた Dashicons のページで確認できます。
この方法の利点は、JavaScript を一行も書かずに済むことと、block.json を PHP 側の register_block_type() が読むため、ブロックが JavaScript で登録される前の段階でもアイコン情報が揃うことです。一方で block.json は JSON なので文字列しか書けません。色を付けたり独自の SVG を使ったりしたい場合は、次に説明する JavaScript 側での指定が必要になります。
registerBlockType 側でオブジェクトを渡して色を付ける
registerBlockType の設定オブジェクトに icon を渡すと、文字列だけでなくオブジェクトの形でも指定できます。オブジェクトには src・foreground・background の3つのキーがあります。
import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import Edit from './edit';
import save from './save';
registerBlockType( metadata.name, {
icon: {
src: 'megaphone', // Dashicons のスラッグ、または SVG 要素
foreground: '#ffffff', // アイコン自体の色
background: '#7e70af', // アイコンの背景色
},
edit: Edit,
save,
} );| キー | 説明 |
|---|---|
src | アイコン本体。Dashicons のスラッグ（文字列）、または SVG の要素を渡す |
foreground | アイコンの色。省略すると背景色から読みやすい色が自動で決まる |
background | アイコンの背景色。インサーターのプレビューなどで使われる |
注意したいのは、block.json にも icon を書いていて、JavaScript 側でも icon を渡した場合は JavaScript 側の指定が使われるという点です。block.json の値を上書きする形になるので、「JSON を書き換えたのにアイコンが変わらない」というときは、まず index.js に icon が残っていないか確認してください。
なお、foreground と background は色を固定してしまう指定です。エディターのテーマ（ライト／ダーク）に馴染ませたい場合はあえて指定せず、既定の色に任せたほうが自然に見えることも多くあります。ブランドカラーを強く出したいブロックに限って使う、くらいの温度感がちょうど良いでしょう。
独自の SVG をアイコンにする
用意されたアイコンに合うものがないときは、自分で描いた SVG をそのまま渡せます。icon（または icon.src）には SVG の要素を渡せるので、アイコン用のファイルを分けておくと見通しが良くなります。
import { SVG, Path } from '@wordpress/primitives';
const noticeIcon = (
<SVG viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
<Path d="M12 3.5 3 20h18L12 3.5zm-1 6h2v5h-2v-5zm0 6.5h2v2h-2v-2z" />
</SVG>
);
export default noticeIcon;@wordpress/primitives の SVG と Path は、WordPress が用意している SVG 要素のラッパーです。素の <svg> / <path> を JSX で書いても動きますが、SVG を使うと必要な属性の補完をコンポーネント側が引き受けてくれるため、コアのブロックもこちらで書かれています。
あとは index.js で読み込んで渡すだけです。
import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import noticeIcon from './icon';
import Edit from './edit';
import save from './save';
registerBlockType( metadata.name, {
icon: noticeIcon,
edit: Edit,
save,
} );viewBox は 24×24 に合わせる
SVG を自作するときに一番つまずきやすいのが viewBox です。ブロックエディターのアイコンは 24×24 の座標系を前提にしており、@wordpress/icons のアイコンもすべて viewBox="0 0 24 24" で作られています。
Illustrator や Figma から書き出した SVG は viewBox="0 0 512 512" のように別の座標系になっていることがよくあります。この場合でも viewBox の比率が正方形であれば表示自体は縮小されて収まりますが、線の太さや余白の取り方が他のアイコンと揃わず、並べたときに浮いて見えます。可能なら 24×24 に作り直すか、書き出し設定で座標系を合わせておくのが無難です。
また、SVG に width / height 属性を直接書き込むのは避けてください。表示場所によってアイコンのサイズは変わるため、寸法は viewBox だけで表し、実サイズは表示側に任せるのが正解です。
SVG に色を直接書かない
<Path fill="#333333" /> のように色を固定すると、その色で塗られたままになります。エディターの配色に追従させたい場合や、前述の foreground で色を変えたい場合は、fill を指定しないでおくのが基本です。どうしても明示したいときは fill="currentColor" にしておけば、文字色に追従する形になります。
複数の色で塗り分けたロゴのようなアイコンは、小さく表示されると潰れてしまいます。ブロックのアイコンは 24px 程度で表示されるものと考えて、単色のシンプルな図形にまとめるのが実用的です。
@wordpress/icons のアイコンを使う
ブロックエディターのツールバーやサイドバーで使われているアイコン群は、@wordpress/icons というパッケージにまとまっています。自分のブロックでも同じアイコンを使えば、エディターの見た目に自然に溶け込みます。
このパッケージは WordPress 本体のスクリプトとして配信されておらず、ビルド結果に同梱される形になります。そのため、使う前に npm でインストールしておく必要があります。
npm install @wordpress/iconsあとは使いたいアイコンを名前付きインポートで読み込み、icon に渡します。アイコン名は image や settings のようなキャメルケースの小文字始まりです。
import { registerBlockType } from '@wordpress/blocks';
import { image } from '@wordpress/icons';
import metadata from './block.json';
import Edit from './edit';
import save from './save';
registerBlockType( metadata.name, {
icon: image,
edit: Edit,
save,
} );色を付けたい場合は、これまでと同じようにオブジェクトの src に渡します。
import { settings } from '@wordpress/icons';
registerBlockType( metadata.name, {
icon: {
src: settings,
background: '#1e1e1e',
foreground: '#ffffff',
},
edit: Edit,
save,
} );Icon コンポーネントで UI にアイコンを表示する
@wordpress/icons は Icon というコンポーネントも提供しています。アイコンを icon プロパティに渡すと、その場に描画してくれるものです。size でピクセル単位の大きさを指定でき、既定は 24 です。
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ToggleControl } from '@wordpress/components';
import { Icon, check, settings } from '@wordpress/icons';
export default function Edit( { attributes, setAttributes } ) {
const { showBadge } = attributes;
const blockProps = useBlockProps();
return (
<>
<InspectorControls>
{ /* PanelBody は icon プロパティを受け取れる */ }
<PanelBody title="表示設定" icon={ settings }>
<ToggleControl
label="バッジを表示する"
checked={ showBadge }
onChange={ ( value ) =>
setAttributes( { showBadge: value } )
}
/>
</PanelBody>
</InspectorControls>
<div { ...blockProps }>
{ showBadge && (
<span className="notice-box__badge">
<Icon icon={ check } size={ 20 } />
確認済み
</span>
) }
</div>
</>
);
}@wordpress/components の Button や ToolbarButton も icon プロパティを持っているので、そちらは Icon で包まずにアイコンをそのまま渡せます。<ToolbarButton icon={ settings } label="設定" /> のような書き方です。Icon を使うのは、ボタン以外の場所に単体でアイコンを置きたいときだと考えておくと分かりやすいでしょう。
ひとつ気を付けたいのは、save の中でアイコンを使うかどうかです。save の出力は記事本文として保存されるため、後からパッケージ側のアイコンの形が変われば保存済みの HTML と食い違い、ブロック検証エラーの原因になります。アイコンはエディター内（edit）の表示に留め、フロント側で必要なら自分のテーマやプラグインの SVG を使うほうが安全です。
Dashicons と @wordpress/icons の違い
どちらも WordPress 界隈で使われるアイコンですが、出自も使い方も別物です。迷ったときのために整理しておきます。
| 項目 | Dashicons | @wordpress/icons |
|---|---|---|
| 提供元 | WordPress 本体に同梱 | npm パッケージ（要インストール） |
| 指定の仕方 | "smiley" のようなスラッグの文字列 | import { image } from '@wordpress/icons' で読み込んだ値 |
block.json に書けるか | 書ける | 書けない（JavaScript 側で指定する） |
| 座標系 | 20×20 | 24×24 |
| 見た目の系統 | 管理画面寄りの少し古いデザイン | ブロックエディターの現行デザインに合う |
| 主な用途 | 管理画面メニュー、手軽なブロックアイコン | ブロックアイコン、エディター内の UI |
ざっくり言えば、手早く済ませたいなら block.json に Dashicons のスラッグ、エディターの見た目に馴染ませたいなら @wordpress/icons という選び分けになります。ブランド性のあるブロックや、どちらにも適した図柄がない場合に独自 SVG を検討する、という順番で考えると迷いません。
アイコンが変わらない・表示されないとき
編集したファイルがビルドに反映されていない
@wordpress/scripts を使っている場合、WordPress が読んでいるのは src/ ではなく build/ の中身です。src/block.json を書き換えただけでは反映されないので、npm run build を実行するか、npm run start で監視状態にしておく必要があります。
ビルドしたのに変わらないときは、ブラウザーのキャッシュが残っている可能性があります。スーパーリロード（Windows は Ctrl+Shift+R、Mac は Cmd+Shift+R）を試してください。それでも古いままなら、register_block_type() に渡しているパスが build ディレクトリを指しているかも確認しましょう。
Dashicons の名前が正しくない
存在しないスラッグを書いてもエラーにはならず、単にアイコンが表示されない（あるいは空白になる）だけなので気付きにくい部分です。"dashicons-smiley" のように接頭辞を付けてしまうのがよくある間違いで、正しくは "smiley" です。スペルに自信がないときは Dashicons の公式ページでスラッグをコピーしてください。
インポートした値が undefined になっている
@wordpress/icons のアイコンは名前付きエクスポートなので、import image from '@wordpress/icons' のようなデフォルトインポートでは取得できません。import { image } from '@wordpress/icons'; と波括弧で囲みます。
名前の綴りも要注意です。存在しない名前をインポートすると値が undefined になり、アイコンがデフォルトの図形に戻ります。インストール後に node_modules/@wordpress/icons の中身を見れば、実際にどんな名前が用意されているかを確認できます。また、インストールを忘れているとビルド時にモジュールが見つからないというエラーになるので、そちらはすぐ気付けるはずです。
自作 SVG が大きすぎて切れる・小さすぎる
図形がはみ出したり、逆に中央に小さく点のように表示されたりする場合は、viewBox と実際のパスの座標が噛み合っていません。たとえば viewBox="0 0 24 24" と書きながら、パスの座標が 0〜500 の範囲で描かれていれば、左上の一部だけが拡大表示されます。デザインツールで書き出した SVG をそのまま貼るとこの状態になりやすいので、viewBox の値と d 属性の数値の桁を見比べてみてください。
まとめ
ブロックのアイコン指定には、block.json に Dashicons のスラッグを書く方法と、registerBlockType の設定で渡す方法の2通りがあります。前者は JSON なので文字列のみ、後者はオブジェクト（src / foreground / background）や SVG 要素も扱えて、両方書いた場合は JavaScript 側が優先されます。
エディターの見た目に馴染ませたいなら @wordpress/icons を npm install して名前付きインポートで使うのが手軽です。同梱の Icon コンポーネントを使えば、サイドバーやブロック内の UI にもアイコンを置けます。独自の SVG を用意する場合は、viewBox を 24×24 に揃え、width / height や固定の fill を書かないこと。この2点を守るだけで、コアのブロックと並べても違和感のないアイコンになります。