@icoglyphs/svg

@icoglyphs/svg

Animated SVG icon web component. One script tag, no dependencies, works everywhere.

Usage

CDN (no install)

<script src="https://cdn.icoglyphs.com/v0/svg.js"></script>

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

jsDelivr

For sandboxed environments (CodePen, JSFiddle, LLM artifacts, iframes):

<script type="module" src="https://cdn.jsdelivr.net/npm/@icoglyphs/svg"></script>

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

npm

npm install @icoglyphs/svg

import '@icoglyphs/svg';

The use attribute

use selects what the icon renders. It accepts:

<!-- 1. An icon alias (recommended) -->
<icoglyph-svg use="arrow-right"></icoglyph-svg>

<!-- 2. A JSON-encoded carves array (advanced) -->
<icoglyph-svg use='[{"primitive":"c4","orientation":0}]'></icoglyph-svg>

// 3. An object or array via the DOM property - no JSON.stringify needed
el.use = { primitive: 'c4', orientation: 0 };
el.use = [{ primitive: 'l', orientation: 45 }, { primitive: 'c4', orientation: 0 }];

A string is treated as raw carves only when it starts with [ or {; otherwise it is looked up as an alias. Browse aliases at icoglyphs.com or GET https://api.icoglyphs.com/v1/ig/aliases.

Prefer aliases. Hand-writing carves (primitive, orientation, spatial) is an advanced, easy-to-get-wrong path; aliases are the stable, intended interface.

Error handling. An unknown alias or a network/API error renders an empty icon (no paths) and logs to the console. The element never throws, so an invalid use value cannot break the surrounding page.

Sizing

<icoglyph-svg> is display: inline-block; width: 1em; height: 1em by default, so it matches the surrounding font size and sits inline with text. A small vertical-align: -0.125em keeps it optically centered on the text baseline.

/* resize via font-size */
icoglyph-svg { font-size: 32px; }

/* or set width/height directly */
icoglyph-svg { width: 32px; height: 32px; }

/* fill a container */
.icon-wrapper icoglyph-svg { width: 100%; height: 100%; }

Styling

Icons use stroke: currentColor by default, so they follow the surrounding text color automatically.

/* color via currentColor */
icoglyph-svg { color: #333; }

/* or set stroke directly */
icoglyph-svg { stroke: #333; }

/* stroke width (defaults to 10, in viewBox units) */
icoglyph-svg { stroke-width: 6; }

/* or via the custom property (inherits, so it can theme a group) */
.toolbar { --icoglyph-stroke-width: 6; }

/* theme all icons in a section */
.dark-section { color: white; }

Icons reserve a margin for the stroke, so typical widths render fully inside the box without clipping at the edges. Very wide strokes (well above the default) may still be clipped.

Animation

Icons morph automatically when you change the use attribute. No configuration needed.

const icon = document.querySelector('icoglyph-svg');
icon.use = 'yes'; // smooth morph animation

// pass a carve object or array directly - no JSON.stringify needed
icon.use = { primitive: 'c', orientation: 0, spatial: [0] };
icon.use = [{ primitive: 'l', orientation: 45, spatial: [0] }, { primitive: 'c', orientation: 0, spatial: [0] }];

// customize timing
icon.animation = { duration: 300 };

Static SVG (no JavaScript)

For GitHub READMEs, emails, or markdown where JS is unavailable:

<img src="https://cdn.icoglyphs.com/svg/arrow-right" alt="Arrow right" width="24" height="24">
<img src="https://cdn.icoglyphs.com/svg/eye?color=%232563eb&stroke-width=4" alt="Eye" width="32" height="32">

Open Graph images

Every icon is available as a 1200x630 social card PNG, rendered on demand (dark background, light icon):

https://cdn.icoglyphs.com/og/arrow-right.png

Available icons

Browse all icons at icoglyphs.com or fetch the list from the API:

GET https://api.icoglyphs.com/v1/ig

Links

• Website: https://icoglyphs.com
• API docs: https://icoglyphs.com/llms.txt