Skip to main content

Icon

SVG icon styling plus a sprite-based Twig component. The .icon class applies size, color and variant rules to any <svg>, so an inline SVG needs no component - just the class. The Twig component looks a symbol up in the shared sprite, so an icon can be referenced by name without inlining any markup.

Usage​

Pass the icon's name as the symbol prop:

{% include '@components/icon/icon.twig' with { symbol: 'close', classes: ['lg'] } only %}

The whole set is browsable in the Library example below, and the Playground's Symbol control lists every name in the sprite. What each icon means is covered on the Icons foundation page.

When to use

  • A button, link, or label needs a supporting symbol
  • The same icon is used in many places and should be served from a single sprite
  • An inline SVG needs consistent sizing and color inheritance

When not to use

  • Decorative brand illustrations - use an <img> or dedicated media component
  • Complex multi-color artwork that breaks under currentColor

Do

  • Use currentColor so icons follow the surrounding text color
  • Pick a size value (xs, sm, md, lg, xl) instead of hardcoding pixel values
  • Use em sizing (.fluid mode) when the icon sits next to text

Don't

  • Don't reference a name that is not in the sprite - it renders as empty space, with no error
  • Don't forget aria-hidden="true" on decorative icons

How the variants work​

Each sprite symbol holds its outline and solid artwork as two groups, and picks between them with a display presentation attribute that reads a custom property. The indirection is not decoration: those groups live inside the shadow tree a <use> element builds, which no CSS selector can reach, and a custom property is the only thing that inherits across that boundary. The artwork values set those properties.

An icon drawn in one variant only carries no such gate, so it keeps rendering the artwork it has whichever class is applied, rather than disappearing.

API​

Props​

PropTypeDefaultDescription
symbolstring-Icon role from the sprite (for example "close"). The published set is in assets.icons of the spec bundle.
icon_sprite_pathstring-Path to the SVG sprite file. Defaults to "/assets/icons.svg".
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.infoIntent-Informational message.
.warningIntent-Warning or caution.
.dangerIntent-Error, destructive, or critical.
.successIntent-Confirmation or completion.
.xsSize-Extra small.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.xlSize-Extra large.
.fluidLayout-Full-width, no max-width.
.outlineArtworkYesWhich of the two drawings a sprite symbol carries is displayed - outline is stroked with an unpainted interior, solid is filled. A symbol drawn in one variant only ignores the choice.
.solidArtwork-Which of the two drawings a sprite symbol carries is displayed - outline is stroked with an unpainted interior, solid is filled. A symbol drawn in one variant only ignores the choice.

Examples​

Library​

Every icon in the sprite, in the default outline variant.

Inline SVG​

Inline <svg> with the .icon class - no component needed.

Sprite​

Twig component referencing a symbol in the shared sprite.

Sizes​

Size values .xs, .sm, .md, .lg, .xl.

Artwork​

Four icons in both variants, including a brand mark.

Standalone vs fluid​

Standalone fixed rem sizing compared with .fluid em sizing that scales with text.

Accessibility​

  • WCAG 2.2 AA
  • A decorative icon carries aria-hidden="true" so assistive tech skips it
  • Passing aria-label (or aria-labelledby) through attributes switches the icon to role="img" and gives it an accessible name
  • Sufficient color contrast when the icon carries meaning via color

Dependencies​

  • button - buttons frequently pair with a leading or trailing icon
  • linklist - list items often use a leading icon