Web Component

HTML Attribute

The <icoglyph-svg> element has a single HTML attribute: use. Pass an icon alias to display it.

<icoglyph-svg use="arrow-right"></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 for the lifetime of the page. 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

The component automatically sets role="img" on the inner SVG and uses the use value as its accessible name (via a <title> element). Screen readers will announce the alias, e.g. "arrow-right".

For decorative icons that sit next to a visible label, hide them from assistive technologies with aria-hidden:

<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 */
}