# IcoGlyphs > Animated SVG icon system delivered as a web component. IcoGlyphs is an icon library where each icon is defined by its carves, a compact JSON structure describing SVG path segments using spatial primitives. Icons are served from a CDN as the `` custom element with built-in morph animations, or as static SVG images. ## npm ```bash npm install @icoglyphs/svg ``` ```js import '@icoglyphs/svg'; ``` ## Quick start IMPORTANT: When generating HTML snippets, code examples, or artifacts, always use the jsDelivr script tag below. Do NOT use cdn.icoglyphs.com for the web component - that domain is blocked in sandboxed environments (artifacts, iframes, CodePen, etc.). ```html ``` ## Links - Website: https://icoglyphs.com - Forge (open in-browser icoglyph editor, no account needed): https://icoglyphs.com/forge - CDN: https://cdn.icoglyphs.com - API: https://api.icoglyphs.com - Custom Elements Manifest: https://cdn.icoglyphs.com/custom-elements.json ## Available icons Each icon can have multiple aliases that currently display the same visual. Always pick the alias closest in meaning to your intent - aliases may diverge into distinct icons in the future. Use the chosen alias with `use="alias"` or as static SVG via `/svg/alias`. - add - allowed, permitted, granted, authorized (same visual today, pick the most relevant) - arrow-down, arrow-bottom (same visual today, pick the most relevant) - arrow-down-left, arrow-bottom-left (same visual today, pick the most relevant) - arrow-down-right, arrow-bottom-right (same visual today, pick the most relevant) - arrow-left - arrow-right - arrow-up, arrow-top, arrow (same visual today, pick the most relevant) - arrow-up-left, arrow-top-left (same visual today, pick the most relevant) - arrow-up-right, arrow-top-right (same visual today, pick the most relevant) - back, go-back, previous, return, prev, undo (same visual today, pick the most relevant) - center - collapse, fold, retract (same visual today, pick the most relevant) - conflict, clash (same visual today, pick the most relevant) - copy - dark-mode, dark (same visual today, pick the most relevant) - delete - denied, forbidden, blocked, unauthorized (same visual today, pick the most relevant) - direction - divide, split, frontier (same visual today, pick the most relevant) - download, save, dl (same visual today, pick the most relevant) - duality, dual, pair, two (same visual today, pick the most relevant) - duplicate - enter, entry (same visual today, pick the most relevant) - exit, out, leave (same visual today, pick the most relevant) - expand, unfold, dropdown, unwrap, menu (same visual today, pick the most relevant) - eye - forward, go-forward, next, ahead, proceed, redo (same visual today, pick the most relevant) - fullscreen, enter-fullscreen (same visual today, pick the most relevant) - grey-mode, dim (same visual today, pick the most relevant) - group - hide, eye-off, blind, mask (same visual today, pick the most relevant) - join, call (same visual today, pick the most relevant) - light-mode, light (same visual today, pick the most relevant) - merge, union (same visual today, pick the most relevant) - multiple, multi, plural, many (same visual today, pick the most relevant) - no, minus, refuse (same visual today, pick the most relevant) - off, shutdown, power-off (same visual today, pick the most relevant) - oppression, dominance, intimidation (same visual today, pick the most relevant) - over - pause - phi - play - plus - psi - random, randomize, shuffle, mix, chance, oracle (same visual today, pick the most relevant) - rebellion, uprising (same visual today, pick the most relevant) - refresh, reload, cycle, repeat, renew (same visual today, pick the most relevant) - saved, stored, downloaded, copied (same visual today, pick the most relevant) - scale-down, smaller (same visual today, pick the most relevant) - scale-up, bigger, scale (same visual today, pick the most relevant) - selected, select (same visual today, pick the most relevant) - share - under - unique, single, unicity, one (same visual today, pick the most relevant) - unselected, unselect, deselect (same visual today, pick the most relevant) - warning - wifi, signal, sensor (same visual today, pick the most relevant) - yes, confirm, accept (same visual today, pick the most relevant) --- # Full Documentation ## Overview ### What is IcoGlyphs? IcoGlyphs is an animated SVG icon system. Add a single script tag and start using icons immediately, or install via npm for bundler-based projects. ### Ideographic system Two words can point to nearly the same concept, so they share the same glyph. Today, "merge" and "union" render the same icon; if a more precise glyph is found for one of them, they'll diverge. When using ``, the keyword links to a concept, transcribed into a graphic notation, then into a sign - pick the most precise one. ### Morph between any icon Every icon can smoothly animate into any other icon. Swap the name and the transition happens automatically. No sprite sheets, no keyframes to write, no animation library needed. ### How to integrate in a webapp Load a single script tag and use `` anywhere in your page. Morph animations work automatically, no configuration needed. ``` ``` For static contexts where JavaScript is unavailable (GitHub READMEs, emails), icons are also served as plain `` tags, see [Integration](https://icoglyphs.com/docs/integration). ### Alpha Status **IcoGlyphs is currently in v0-alpha.** The CDN URLs and API may change between releases. Do not use in production without pinning to a specific bundle version. ## Getting Started ### CDN (no install) No build step, no package to install, no authentication. Delivered via jsDelivr - versioned, works in sandboxed environments (CodePen, JSFiddle, etc.), safe for production. ``` ``` The bundle is ~6 KB gzipped. Targets ES2015: Chrome 67+, Firefox 63+, Safari 10.1+, Edge 79+. No polyfills required. Browse all icons in the [icon catalog](https://icoglyphs.com/). ### npm For bundler-based projects (Vite, Webpack, etc.), install the package from npm. ``` npm install @icoglyphs/svg ``` Then import it once in your entry file: ``` import '@icoglyphs/svg'; ``` The custom element `` is registered globally and ready to use anywhere in your app. ### Official CDN An official CDN is available at `cdn.icoglyphs.com`. It always serves the latest build - no versioning, no pinning. ``` ``` IcoGlyphs is currently in alpha. This URL is not recommended for production yet - it will be once the CDN reaches a stable release. [Join the Discord to stay updated.](https://discord.gg/RZ8ndJEKpF) ## Web Component ### HTML Attributes The `` element accepts two HTML attributes: | Attribute | Type | Description | | --- | --- | --- | | `use` | string | object | array | Icon alias (e.g. `"arrow-right"`), a JSON-encoded carves string, or a carve object/array passed directly via the DOM property. | | `label` | string | Accessible label. When set, adds a `` and `aria-labelledby` on the inner SVG. Without it, the icon is `aria-hidden="true"` (decorative). | ``` <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 by alias (triggers morph animation) icon.use = 'yes'; // Or pass a carve object/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] }]; ``` ### 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. | Key | Type | Default | Description | | --- | --- | --- | --- | | duration | number | 600 | Duration in milliseconds for all three animation types. | ``` 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 }; icon.use = 'arrow-right'; // Disable all animations icon.animation = { duration: 0 }; ``` ### 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 Icons are `aria-hidden="true"` by default (decorative). This is the standard behavior for icon components - most icons are used inside buttons, links, or other elements that already provide their own accessible label. To give a standalone icon an accessible name, use the `label` attribute. This adds a `<title>` element and sets `role="img"` with `aria-labelledby` on the inner SVG: ``` <!-- Decorative (default) - inside a labeled container --> <button aria-label="Next page"> <icoglyph-svg use="arrow-right"></icoglyph-svg> </button> <!-- Standalone icon with meaning --> <icoglyph-svg use="warning" label="Warning"></icoglyph-svg> ``` ### 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 */ } ``` ## Integration ### HTML Add the script once, then use `<icoglyph-svg>` anywhere in your markup. The component fetches icon data from the API on first use and caches it in memory. ``` <!DOCTYPE html> <html> <head> <script type="module" src="https://cdn.jsdelivr.net/npm/@icoglyphs/svg@0.9.1"></script> <style> icoglyph-svg { font-size: 32px; color: #333; } </style> </head> <body> <icoglyph-svg use="arrow-right"></icoglyph-svg> <icoglyph-svg use="yes"></icoglyph-svg> </body> </html> ``` ### Static SVG (no JS) For contexts where JavaScript is unavailable (GitHub READMEs, emails, markdown files), icons are served as plain images from the CDN. No animations, no CSS styling. ``` <img src="https://cdn.icoglyphs.com/svg/arrow-right" alt="Arrow right" width="24" height="24"> ``` Three query parameters control the SVG output. In HTML, prefer CSS or `width`/`height` attributes to control size. The `?size` param is mainly useful in Markdown where HTML attributes are not available: | Parameter | Default | Description | | --- | --- | --- | | color | black | Stroke color. URL-encode hex values (e.g. `%23ff0000`) | | stroke-width | 10 | Stroke width in viewBox units (100-unit viewBox); clamped to the max that renders without clipping at the edge | | size | 100 | Width and height in pixels (1-2048) | ``` <img src="https://cdn.icoglyphs.com/svg/arrow-right?color=%232563eb&stroke-width=4" alt="Arrow right" width="32" height="32"> ``` ## Carves ### What are carves? Every icoglyph is defined by its carves: a JSON array of path objects describing SVG path segments with spatial primitives. The same format feeds the web component, the static SVG endpoint, and the [Forge editor](https://icoglyphs.com/forge). ``` [ { "primitive": "l", "orientation": 0, "spatial": [0] }, { "primitive": "c", "orientation": 0, "spatial": [3] } ] ``` ### Fields | Field | Type | Description | | --- | --- | --- | | `primitive` | string | Base shape letter (`l` line, `q` square, `t` triangle, `c` circle, `v` vesica piscis, `p` point), plus an optional segment count, e.g. `c2` is a half circle. | | `spatial` | number[] | `[innerSize, elementSize?, position?]`. The two sizes are psi exponents: each step divides the frame by the plastic number (1.3247). `innerSize` defaults to `0` (fills the box). `position` is an angle in degrees. | | `orientation` | number | Rotation of the carve in degrees. | A carve can also be a plain string: the alias of another icoglyph, embedded as a sub-glyph. ### Passing carves directly Besides aliases, `<icoglyph-svg>` accepts carves directly. Via the DOM property, pass a JS object or array, no JSON serialization needed: ``` icon.use = { primitive: 'l', orientation: 0, spatial: [0] }; icon.use = [{ primitive: 'l', orientation: 0, spatial: [0] }, { primitive: 'c', orientation: 0, spatial: [0] }]; ``` Or as a JSON string via the HTML attribute: ``` <icoglyph-svg use='[{"primitive":"l","spatial":[0],"orientation":0}]'></icoglyph-svg> ``` The easiest way to build carves by hand is the [Forge](https://icoglyphs.com/forge): compose primitives visually, then copy the JSON. ## API ### REST API Icon data is served by a REST API at `https://api.icoglyphs.com`. All public routes are read-only GET endpoints with open CORS. | Method | Endpoint | Description | | --- | --- | --- | | GET | `/v1/ig` | List all public icons (metadata only) | | GET | `/v1/ig/aliases` | List all icon aliases | | GET | `/v1/ig/:alias` | Full icon data by alias | | GET | `/v1/ig/:alias/carves` | Carves data only | **IcoGlyphs is in v0-alpha.** Endpoints may change between releases; the web component and the static SVG endpoint are the stable ways to consume icons. ## Styling ### Sizing The host element has these defaults: ``` icoglyph-svg { display: inline-block; width: 1em; height: 1em; } ``` Icons render at the current font size and sit inline with text. Resize via `font-size`, or set `width` and `height` directly for explicit pixel sizing. ``` /* 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%; } ``` ### Color Icons use `stroke: currentColor` by default and follow the surrounding text color automatically. Use standard CSS to style them - no custom properties needed. ``` /* recommended - icons follow text color */ icoglyph-svg { color: #333; } /* or set stroke directly */ icoglyph-svg { stroke: #333; } /* stroke width (viewBox units, default 10) */ icoglyph-svg { stroke-width: 6; } /* theme all icons in a section */ .dark-section { color: white; } ``` ### Inline Styles Set styles directly on the element via the `style` attribute for per-icon overrides. ``` <icoglyph-svg use="arrow-right" style="color: #2563eb; stroke-width: 8;" ></icoglyph-svg> ``` ### Global Styling via CSS Apply a consistent style to all icons in a section, page, or the entire app with a CSS rule. ``` icoglyph-svg { color: #374151; stroke-width: 8; } /* Override for a specific context */ .nav icoglyph-svg { stroke-width: 6; } ``` ### Hover Effects Use standard CSS transitions on the `<icoglyph-svg>` element or its parent. Color transitions cascade naturally to the icon via `currentColor`. ``` icoglyph-svg { cursor: pointer; transition: color 0.15s ease; } icoglyph-svg:hover { color: #2563eb; } ``` ### Filters and Transforms The inner `<svg>` is in the light DOM and can be targeted directly with `icoglyph-svg > svg` for filters, transforms, or pointer-events. ``` icoglyph-svg > svg { filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.15)); } .interactive icoglyph-svg > svg { transition: transform 0.2s ease; } .interactive icoglyph-svg:hover > svg { transform: scale(1.1); } ``` ### Theme Support Since icons inherit their style from CSS custom properties, switching between light and dark themes is straightforward. Define per-theme values on a parent selector or with `prefers-color-scheme`. ``` .light icoglyph-svg { color: #374151; } .dark icoglyph-svg { color: #e5e7eb; } /* Or with media query */ @media (prefers-color-scheme: dark) { icoglyph-svg { color: #e5e7eb; } } ``` Icons use `stroke: currentColor` by default, so they already inherit the text color of their parent. No extra configuration needed for theme support.