Web Component

HTML Attributes

The <icoglyph-svg> element accepts two HTML attributes:

<icoglyph-svg use="arrow-right"></icoglyph-svg>

<!-- With explicit accessible label -->
<icoglyph-svg use="arrow-right" label="Go to next page"></icoglyph-svg>

The component fetches the icon data from the API on first use and caches it in memory. Subsequent uses of the same alias are served from the cache.

Changing Icons Programmatically

Set the use property via JavaScript to switch icons. This triggers a smooth morph animation between the two states.

const icon = document.querySelector('icoglyph-svg');

// Switch icon (triggers morph animation)
icon.use = 'yes';

Animation

The component animates automatically, no extra code needed. Three transitions are built in: entry (paths expand from center on mount), exit (paths collapse on unmount), and morph (smooth interpolation between two icons when use changes). The first render skips the entry animation to avoid a flash on page load.

Animation behavior is controlled via the animation JavaScript property (not an HTML attribute). Assign an object with any of the following keys. Omitted keys keep their current values.

const icon = document.querySelector('icoglyph-svg');

// Changing 'use' triggers the morph automatically (600ms by default)
icon.use = 'yes';

// Adjust timing before switching
icon.animation = { duration: 300, ease: 'cubic-bezier(0.43, 0.13, 0.23, 0.96)' };
icon.use = 'arrow-right';

// Disable all animations
icon.animation = { duration: 0, ease: 'linear' };

Caching

When an icon is fetched by alias, the result is cached in memory (LRU, up to 200 entries). The cache stores the data under all of the icon's aliases, so requesting any alias for the same icon only triggers one network call.

Accessibility

When using an alias string (e.g. use="arrow-right"), the component automatically adds a <title> element with the alias as accessible name and sets role="img" on the inner SVG. For a more descriptive label, use the label attribute:

<!-- Alias used as accessible name -->
<icoglyph-svg use="arrow-right"></icoglyph-svg>

<!-- Explicit label overrides the alias -->
<icoglyph-svg use="arrow-right" label="Go to next page"></icoglyph-svg>

When using raw JSON carves without a label, the SVG is marked aria-hidden="true" (decorative). Add label to make it accessible:

<!-- Decorative: aria-hidden="true" -->
<icoglyph-svg use='[{"primitive":"l","spatial":[1],"orientation":180}]'></icoglyph-svg>

<!-- Accessible: label provides the name -->
<icoglyph-svg use='[{"primitive":"l","spatial":[1],"orientation":180}]' label="Checkmark"></icoglyph-svg>

For decorative icons that sit next to a visible text label, you can force aria-hidden by omitting the label attribute and using JSON carves, or by setting aria-hidden="true" on the host element:

<button>
  <icoglyph-svg use="arrow-right" aria-hidden="true"></icoglyph-svg>
  Next
</button>

Loading and Error Handling

While the icon data is being fetched, the component renders nothing, the element is empty. There is no built-in loading placeholder. Once the data arrives the icon renders immediately. Subsequent uses of the same alias are served from memory cache with no delay.

If an alias does not exist or the API is unreachable, the component remains empty. No error is thrown and no custom event is dispatched. There is currently no programmatic way to detect load success or failure.

No built-in placeholder is displayed. To show a visual fallback, style the host element itself. The icon will render on top when it loads, and the fallback remains visible if it fails:

icoglyph-svg {
  display: inline-block;
  background: #f3f4f6;
  border-radius: 4px;
  /* Icon renders on top when loaded, fallback shows on error */
}