Icons & the WordPress Icon API

WP Rig 3.5 wires your theme’s SVG icons into the native WordPress Icon API (WP 7.1). Drop SVG files into assets/icons/ and they register themselves on init — appearing in the editor’s Icon block, in REST discovery, and in your templates via a template tag. It works in every paradigm: classic, universal, and block-based, with no component install required.

Quick start

Add SVG files to your theme’s icons directory:

assets/icons/
├── arrow-right.svg
├── check-circle.svg
└── menu-icon.svg

That’s it. Each file registers under the wprig-icons collection (namespaced wprig-icons/<slug>, where the slug is the filename without extension) via wp_register_icon_collection() and wp_register_icon(). The editor discovers them through the native REST endpoints.

Using icons in templates

The wprig_icon() template tag renders an icon. It prefers the natively registered icon and falls back to reading the file directly — so it keeps working on WordPress versions before 7.1:

wp_rig()->wprig_icon( 'arrow-right', array( 'class' => 'my-icon' ) );

Child theme overrides

An icon in the child theme’s assets/icons/ directory overrides a parent icon with the same filename — swap brand icons per-client without touching the parent theme.

Markup constraints

WordPress core sanitizes registered icon content to <path> and <polygon> elements only. Icons built from other primitives — <rect>, <circle>, <line>, <polyline> — are skipped at registration (with a wp_rig_log note) rather than registered blank. Convert them to path/polygon markup; the starter’s menu-icon.svg and dropdown-symbol.svg were converted for exactly this reason.

Opting out

Disable collection registration entirely (icons remain available via file reads):

add_filter( 'wp_rig_icons_register_collection', '__return_false' );

On WordPress versions before 7.1, registration silently no-ops — wprig_icon() keeps working from the files, so templates never break across WP versions.

Bringing in icon libraries

Icon libraries (Feather, Lucide, Heroicons, Phosphor, and friends) export plain SVGs that work as-is: download the set, prune to the icons you use, drop them into assets/icons/, and rename files to kebab-case slugs (chevron-right.svg → wprig-icons/chevron-right). Watch the markup constraint: many libraries build icons from <rect>/<circle>/<line> primitives — run them through a converter (or SVGO with shape-to-path) before committing. Keep stroke/fill attributes inline on the <svg> element so they survive core’s sanitization.

See Theme Paradigms for how the same icons ship in classic and block themes, and Building Custom Blocks (the --icon flag scaffolds block icons from the same assets).