Icon

Props

• label: string (optional) -- accessible name announced by screen readers for meaningful icons
• decorative: boolean (default: false) -- when true, hides the icon from assistive technology and removes the img role
• children: slot (required) -- the icon content (text, SVG, or other markup)
• ...restProps: unknown -- additional attributes spread onto the <span> element

Keyboard Interactions

None -- this component is a passive container. Keyboard behavior depends on the parent interactive element (such as a button wrapping the icon).

ARIA

• role="img" -- applied to meaningful icons so assistive technology treats the span as an image
• aria-label="..." -- provides the accessible name for meaningful icons
• aria-hidden="true" -- applied when decorative is true, hiding the icon from the accessibility tree

When to Use

• Use to display a visual symbol representing an action, object, or concept in buttons, menus, toolbars, or navigation.
• Use with decorative for icons that are purely visual and have adjacent text labels.
• Avoid using a meaningful icon without a label prop; screen reader users would miss the icon's purpose.

When Not to Use

• Do not use as the only target of a click — wrap interactive icons in IconButton or another button so they pick up button semantics and focus styles.
• Do not use to render a single emoji character that already has a textual meaning — use Emoji for that.
• Do not use as a substitute for a labeled image with caption — use Figure for content imagery.
• Do not use without label for an icon that conveys meaning standalone, and do not pass a label to a decorative icon.

Headless

This headless component provides a <span> with role="img" and aria-label for meaningful icons, or aria-hidden="true" for decorative icons. The consumer provides all visual content (SVG, text characters, icon fonts) and styling.

Styles

The consumer provides all CSS styling. The component renders with a .icon class for targeting. No default styles are included — this is a fully headless component.

Testing

• Verify the component renders a <span> element with class icon
• Verify role="img"` -- applied to meaningful icons so assistive technology treats the span as an image
• Verify aria-label="..."` -- provides the accessible name for meaningful icons
• Verify pass-through attributes are applied

Advice

• Designers: Ensure icons are visually clear at small sizes. Pair icons with text labels when the meaning may be ambiguous. Maintain consistent icon sizing across the interface.
• Developers: Set decorative={true} when the icon is adjacent to a text label that conveys the same meaning. Always provide label for standalone icons.

Implementation Notes

• Renders a <span> element as the icon wrapper
• Uses role="img" for meaningful icons that convey information
• Uses aria-hidden="true" for decorative icons that should be ignored by screen readers
• When decorative is true, the role attribute is omitted entirely
• Supports rest props spread for consumer customization
• Consumer provides icon content via the children slot

Related components

• icon-button — a button containing only an icon with a required accessible label
• emoji — a single emoji character with accessible name
• qr-code — a QR code image generated from text or URL data

References

• WAI-ARIA img role: https://www.w3.org/TR/wai-aria-1.2/#img
• WAI-ARIA Practices - Images: https://www.w3.org/WAI/tutorials/images/decorative/