Icons

Inline SVG icons from Iconify collections, injected at build time. Source files stay clean (one Handlebars call), compiled HTML contains pure SVG ready for copy-paste into WordPress.

{{icon "set:name"}}

Helper defined in vite-helpers/icon.js and registered in both Vite configs. Each icon set's JSON is loaded once per build and cached in memory.

Browse all 200+ available collections at icon-sets.iconify.design.

Quick Start

First positional argument is "set:name". Any hash argument is forwarded as an attribute on the root <svg>.

Default 1em × 1em

{{icon "lucide:arrow-right"}}
{{icon "bi:cart"}}

With class

{{icon "lucide:check-circle" class="text-success"}}
{{icon "lucide:alert-triangle" class="text-warning"}}
{{icon "lucide:x-circle" class="text-danger"}}

Custom size

{{icon "lucide:zap" width="16" height="16"}}
{{icon "lucide:zap" width="48" height="48"}}

Collections

Each collection is installed as an npm package. Use its prefix in the icon id.

Installed

Prefix Collection Icons lucide Lucide — modern outline icons, currentColor + uniform stroke ~1700 bi Bootstrap Icons — matches Bootstrap aesthetic ~2000

// add more collections
npm install --save-dev --legacy-peer-deps @iconify-json/mdi
npm install --save-dev --legacy-peer-deps @iconify-json/tabler
npm install --save-dev --legacy-peer-deps @iconify-json/heroicons

Attributes

Any hash argument is forwarded onto the root <svg>. User values override defaults.

Common attributes

Attribute Default Description class — CSS classes (Bootstrap utilities, custom, etc.) width 1em Pixel value or any CSS length height 1em Pixel value or any CSS length style — Inline style declaration role — Accessibility role (e.g. img) aria-label — Accessible name when the icon conveys meaning aria-hidden — Set to true for purely decorative icons

// decorative icon
{{icon "lucide:arrow-right" aria-hidden="true"}}

// meaningful icon
{{icon "lucide:trash-2" class="text-danger" role="img" aria-label="Delete"}}

// arbitrary inline style
{{icon "lucide:star" style="color: gold;" width="24" height="24"}}

Sizing & Coloring

Icons inherit text size via 1em defaults and text color via currentColor.

Scales with font-size

Small text

Medium text

Large text

Display text

// same call — different parent font-size
<p class="fs-6">Small {{icon "lucide:arrow-right"}}</p>
<p class="fs-2">Large {{icon "lucide:arrow-right"}}</p>

Inherits color

Primary

Success

Warning

Danger

Muted

// icon picks up its parent's text color
<div class="text-primary">{{icon "lucide:bookmark"}}</div>
<div class="text-danger">{{icon "lucide:bookmark"}}</div>

Common Patterns

Recipes for typical UI uses.

Button with icon

<button class="btn btn-primary d-inline-flex align-items-center gap-2">
  {{icon "lucide:download"}} Download
</button>

Icon-only button aria-label required

<button class="btn btn-light" aria-label="Settings">
  {{icon "lucide:settings" aria-hidden="true"}}
</button>

Inline list bullets

Inline SVG, no font loading
Inherits currentColor and font-size
Works in WordPress copy-paste workflow

<li class="d-flex align-items-center gap-2">
  {{icon "lucide:check" class="text-success"}} List item
</li>

Caveats

Things to know before going to production.

Stroke width

Lucide bakes stroke-width into inner SVG groups, so passing stroke-width on the outer <svg> may have no visual effect. To customize, target inner elements via CSS:

.icon-thin svg path,
.icon-thin svg [stroke] { stroke-width: 1; }

// then
{{icon "lucide:settings" class="icon-thin"}}

Missing icons

If an icon or collection is missing, the helper renders a dashed-outline placeholder with an aria-label describing the issue, plus a console warning during build. This keeps errors visible without breaking the build.

// these produce visible placeholders + console warnings
{{icon "lucide:does-not-exist"}}
{{icon "unknown-collection:foo"}}

Output size

Every {{icon}} call inlines the full SVG body in the compiled HTML. For pages with many repeated icons, expect the HTML to grow accordingly. This is the intended trade-off — no font/sprite to load, and the HTML is portable (WordPress paste).