Accessibility

Every StateGlyph icon ships with built-in ARIA support, reduced-motion handling, and predictable focus behavior.

Built-in features

Decorative by default

Icons render with aria-hidden="true" and no role. This is correct when the icon appears alongside text that already describes the action — like a button label.

Semantic mode

Set decorative={false} and the icon gains role="img" and an aria-label derived from the state definition. Override with the label prop when needed.

No focusable SVGs

Every SVG renders with focusable="false" to prevent unexpected focus outlines in IE/Edge legacy and assistive technology.

Reduced motion

Continuous states (like loading spinners) use CSS animations that respect prefers-reduced-motion. When enabled, animations are effectively disabled.

Decorative mode

When an icon appears next to a text label that already describes the action, keep the default decorative={true}. The icon is hidden from the accessibility tree:

Decorative usage

// Decorative — the default// The icon is purely visual; nearby text already// conveys the meaning.<UploadStateIcon state="idle" />
// Equivalent to:<UploadStateIcon state="idle" decorative={true} />
// Rendered SVG output:// <svg aria-hidden="true" focusable="false" ... />

Semantic mode

When the icon is the only visual indicator of state — for example, a standalone status icon — set decorative={false}. Screen readers will announce the state:

Semantic usage

// Semantic — the icon conveys information// Use when the icon is the only indicator of state.<UploadStateIcon  state="success"  decorative={false}/>
// Rendered SVG output:// <svg role="img" aria-label="Upload complete" focusable="false" ... />
// Custom label override:<UploadStateIcon  state="success"  decorative={false}  label="File uploaded successfully"/>

When to use each mode

decorativeIcon appears inside a <button>Upload</button> — the button text already conveys meaning.

semanticIcon is a standalone status indicator — no surrounding text explains what it means.

Reduced motion

Some states are marked continuous: true (e.g. a loading spinner). These use CSS animations that are automatically disabled when the user enables the prefers-reduced-motion setting:

CSS

/* StateGlyph docs include this — add it to your project */@media (prefers-reduced-motion: reduce) {  *,  *::before,  *::after {    animation-duration: 0.01ms !important;    transition-duration: 0.01ms !important;  }}

Testing accessibility

StateGlyph outputs data-state-icon and data-state attributes on every SVG. Use these with Testing Library or similar tools:

Testing example

// Test with data attributesconst icon = screen.getByRole("img", {  name: "Upload complete",});expect(icon).toHaveAttribute("data-state", "success");expect(icon).toHaveAttribute("data-state-icon", "upload");