Browse Components

Icon

Named inline SVG icons with direct access to every path and group.

With text

Use a named icon beside a visible action label.

View Code

HTML

<button class="btn" type="button">
  <span class="icon" data-icon="check" aria-hidden="true">
  </span>
  Save Changes
</button>

Icon-only controls

The button owns the accessible name and a comfortable touch target.

View Code

HTML

<div class="cluster">
  <button class="btn secondary btn-icon" type="button" aria-label="Search">
    <span class="icon" data-icon="search" aria-hidden="true">
    </span>
  </button>
  <button class="btn secondary btn-icon" type="button" aria-label="Settings">
    <span class="icon" data-icon="settings" aria-hidden="true">
    </span>
  </button>
</div>

Sizes

Keep the drawing size independent of the control’s hit target.

View Code

HTML

<div class="cluster">
  <span class="icon icon-small" data-icon="user" aria-label="Small user icon">
  </span>
  <span class="icon" data-icon="user" aria-label="Default user icon">
  </span>
  <span class="icon icon-large" data-icon="user" aria-label="Large user icon">
  </span>
</div>

Hover and focus animation

Hover or keyboard-focus the button to draw its checkmark. The circle stays still: only the SVG path animates. Touch retains the complete icon, and reduced motion stays static.

View Code

HTML

<button class="btn secondary" type="button">
  <span class="icon" data-icon="check-circle" data-icon-motion="draw" aria-hidden="true">
  </span>
  Mark Complete
</button>

Meaningful icon

Provide an accessible name and a readable fallback for standalone symbols.

View Code

HTML

<span class="icon" data-icon="check-circle" aria-label="Completed">
  <span class="sr-only">
    Completed
  </span>
</span>

Motion disabled

Disable motion for a region while keeping the complete icon and focus feedback.

View Code

HTML

<div data-motion="none">
  <button class="btn secondary" type="button">
    <span
      class="icon"
      data-icon="check-circle"
      data-icon-motion="draw"
      aria-hidden="true"
    >
    </span>
    Mark Complete
  </button>
</div>

Installation

Download these files into the matching paths in your project, or use Create to assemble a kit. Include each dependency once. Do not also load app.css.

base.css icon.css button.css icon.js Selected icons

Add to your page

<link rel="stylesheet" href="/library/assets/base.css">
<link rel="stylesheet" href="/library/assets/icon.css">
<link rel="stylesheet" href="/library/assets/button.css">
<script defer src="/library/assets/icon.js"></script>
<script defer src="/library/icons/icon.js"></script>

17,904 bytes CSS including base · 4,560 bytes runtime JavaScript

Usage

Setup

Load icon.css and icon.js, then the selected registration file. Documentation and kits provide that file separately so examples stay readable. There are no fetches or full-collection downloads. Register additional icons explicitly with layoutIcon.register({name: svgSource}).

Direct control

The rendered SVG lives directly inside the span. Target [data-icon="check-circle"] > svg > path from CSS, or listen for icon:ready and use event.detail.svg to change an individual path. Refresh preserves your changes until the name or registered drawing changes.

Accessibility

Decorative icons are hidden from assistive technology. Label meaningful icons with aria-label, and label icon-only buttons on the button. Keep a 44px target. With JavaScript disabled, visible labels remain; include fallback text when an icon is the only content.

Lifecycle

Call layoutIcon.refresh(root) after inserting elements or changing data-icon. Call destroy(element) before removal to restore its original content and attributes. Missing icons reserve their dimensions and use data-icon-state="missing". Registering them later resolves the placeholder.

Motion

data-icon-motion="draw" is intended for check/check-circle paths. For other animations use the inline SVG parts, shared motion tokens, hover and focus-visible together, and reduced-motion and data-motion=none fallbacks. Do not communicate state only through animation.

Building with AI? The AI Manifest has these notes and the full contract. See the AI Guide.