# 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 `<icoglyph-svg>` custom element with built-in morph animations, or as static SVG images.

## Quick start

### Static SVG (no JavaScript, no auth)

```html
<img src="https://cdn.icoglyphs.com/svg/arrow-right" alt="Arrow right" />
```

### Web component (full animations, no auth required)

```html
<script src="https://cdn.icoglyphs.com/loader.js"></script>
<icoglyph-svg use="arrow-right"></icoglyph-svg>
```

## Styling with CSS custom properties

The `<icoglyph-svg>` element exposes these CSS custom properties:

| Property                | Default  | Description                    |
|-------------------------|----------|--------------------------------|
| `--ig-stroke`           | grey     | Stroke color                   |
| `--ig-stroke-width`     | 0.4rem   | Stroke width                   |
| `--ig-stroke-linejoin`  | round    | Line join style                |
| `--ig-stroke-linecap`   | round    | Line cap style                 |
| `--ig-stroke-opacity`   | 1        | Stroke opacity                 |
| `--ig-fill`             | none     | Fill color                     |
| `--ig-transition`       | 0.75s    | CSS transition for animations  |

Example:

```css
icoglyph-svg {
  --ig-stroke: #333;
  --ig-stroke-width: 3px;
  --ig-fill: none;
}
```

The inner `<svg>` element is exposed via `::part(svg)` for additional styling.

## Carves format

Carves is a JSON array of path objects. Each object describes an SVG path using these fields:

- `primitive` — path primitive type (`l`, `q`, `t`, `c`, `v`)
- `spatial` — coordinate data for the path
- `orientation` — rotation / positioning data

You can pass carves directly as a JSON string:

```html
<icoglyph-svg use='[{"primitive":"l","spatial":[0,-30,20,10]}]'></icoglyph-svg>
```

Or use an icon alias which resolves via the API:

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

## API

The REST API serves icon data at `https://api.icoglyphs.com`.

| Method | Endpoint                      | Description                    | Auth     |
|--------|-------------------------------|--------------------------------|----------|
| GET    | `/v1/ig`                      | List all public icons          | No       |
| GET    | `/v1/ig/:alias`               | Full icon data by alias        | No       |
| GET    | `/v1/ig/:alias/carves`        | Carves data only               | No       |

## Links

- Website: https://icoglyphs.com
- 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)
- conflict, clash (same visual today, pick the most relevant)
- copy
- dark-mode
- delete
- denied, forbidden, blocked, unauthorized (same visual today, pick the most relevant)
- 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)
- 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
- group
- hide, eye-off, blind, mask (same visual today, pick the most relevant)
- light-mode
- 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)
- oppression, dominance, intimidation (same visual today, pick the most relevant)
- over
- 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 (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)
- unselect, deselect (same visual today, pick the most relevant)
- 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 icon system served from a CDN. No package to install, no build step, no configuration. Add a single script tag and start using icons immediately.

### 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 it works


Load a single script tag and use &lt;icoglyph-svg&gt; anywhere in your page. Morph animations work automatically, no configuration needed.

```
<script src="https://cdn.icoglyphs.com/loader.js"></script>
<icoglyph-svg use="arrow-right"></icoglyph-svg>
```

For static contexts where JavaScript is unavailable (GitHub READMEs, emails), icons are also served as plain &lt;img&gt; tags, see 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


### Quick Start


No build step, no package to install, no authentication. Add the loader script once and use &lt;icoglyph-svg&gt; anywhere in your page.

```
<script src="https://cdn.icoglyphs.com/loader.js"></script>

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

The loader script is under 300 bytes and loads the bundle (~26 KB gzipped) asynchronously and never blocks page rendering. Targets ES2015: Chrome 67+, Firefox 63+, Safari 10.1+, Edge 79+. No polyfills required. Browse all icons in the icon catalog.


## Web Component


### HTML Attribute


The &lt;icoglyph-svg&gt; 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.

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| duration | number | 600 | Duration in milliseconds for all three animation types. |
| ease | string | "linear" | CSS easing function applied to the transition. |

```
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 &lt;title&gt; 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 */
}
```


## Integration


### HTML


Add the loader script once, then use &lt;icoglyph-svg&gt; 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 src="https://cdn.icoglyphs.com/loader.js"></script>
  <style>
    icoglyph-svg {
      --ig-stroke: #333;
      --ig-stroke-width: 0.4rem;
      width: 32px;
      height: 32px;
    }
  </style>
</head>
<body>
  <icoglyph-svg use="arrow-right"></icoglyph-svg>
  <icoglyph-svg use="yes"></icoglyph-svg>
</body>
</html>
```

### React


Web components work in React. Load the script in your index.html or dynamically in a useEffect. Use the element directly in JSX.

```
// Load once in index.html:
// <script src="https://cdn.icoglyphs.com/loader.js"></script>

function Icon({ name, size = 24 }) {
  return (
    <icoglyph-svg
      use={name}
      style={{ width: size, height: size }}
    />
  );
}

// Usage
<Icon name="arrow-right" size={32} />
```

React 18: Properties like animation must be set via a ref because React 18 does not forward non-string props to custom elements. React 19 handles this automatically.React 19 and the use attribute: use is also the name of a React 19 built-in hook. As a prop on a custom element it works correctly (JSX does not confuse it with the hook) but you may see a linter warning. If your setup flags it, use a wrapper component that reads its own prop and sets the attribute via a ref.

```
import { useRef, useEffect } from 'react';

function AnimatedIcon({ name, duration = 300 }) {
  const ref = useRef(null);

  useEffect(() => {
    if (ref.current) {
      ref.current.animation = { duration };
    }
  }, [duration]);

  return <icoglyph-svg ref={ref} use={name} />;
}
```

### Next.js


Load the script in your root layout.js using the Script component with strategy="beforeInteractive". Mark any component that uses &lt;icoglyph-svg&gt; with "use client" since custom elements are client-side only.

```
// app/layout.js
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Script src="https://cdn.icoglyphs.com/loader.js" strategy="beforeInteractive" />
        {children}
      </body>
    </html>
  );
}
```

```
// components/Icon.jsx
'use client';

export function Icon({ name, size = 24 }) {
  return (
    <icoglyph-svg
      use={name}
      style={{ width: size, height: size }}
    />
  );
}
```

### Vue


Tell Vue to ignore the custom element to prevent warnings. Load the script globally in your index.html.

```
// vite.config.js
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: tag => tag === 'icoglyph-svg'
        }
      }
    })
  ]
});
```

Then use the component in your templates:

```
<template>
  <icoglyph-svg
    :use="iconName"
    :style="{ width: size + 'px', height: size + 'px' }"
  />
</template>

<script setup>
defineProps({
  iconName: { type: String, required: true },
  size: { type: Number, default: 24 }
});
</script>
```

### Svelte 5


Svelte 5 handles custom elements natively, no configuration needed. The example below uses Svelte 5 runes syntax ($props()).

```
<script>
  let { name = 'arrow-right', size = 24 } = $props();
</script>

<icoglyph-svg
  use={name}
  style="width: {size}px; height: {size}px;"
/>
```

### 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 output:

| Parameter | Default | Description |
| --- | --- | --- |
| color | black | Stroke color. URL-encode hex values (e.g. %23ff0000) |
| stroke-width | 6 | Stroke width in viewBox units (100-unit viewBox) |
| size | 100 | Width and height in pixels (1–2048) |

```
<img src="https://cdn.icoglyphs.com/svg/arrow-right?color=%232563eb&stroke-width=4&size=32">
```


## Styling


### CSS Custom Properties


The &lt;icoglyph-svg&gt; web component renders inside a Shadow DOM. All visual styling is controlled through CSS custom properties that pierce the shadow boundary.

| Property | Default | Description |
| --- | --- | --- |
| --ig-stroke | grey | Stroke color of the icon paths |
| --ig-stroke-width | 0.4rem | Stroke width of the icon paths |
| --ig-stroke-linecap | round | Line cap style: butt, round, square |
| --ig-stroke-linejoin | round | Line join style: miter, round, bevel |
| --ig-stroke-opacity | 1 | Stroke opacity (0–1) |
| --ig-fill | none | Fill color of the icon paths |
| --ig-transition | none | CSS transition applied to the SVG element for external effects (e.g. opacity, transform on hover). Does not affect path morph animations. Use the animation property for those. |

### Inline Styles


Set custom properties directly on the element via the style attribute for per-icon overrides.

```
<icoglyph-svg
  use="arrow-right"
  style="--ig-stroke: #2563eb; --ig-stroke-width: 0.5rem; --ig-fill: rgba(37, 99, 235, 0.1);"
></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 {
  --ig-stroke: #374151;
  --ig-stroke-width: 0.35rem;
  --ig-stroke-linecap: round;
  --ig-stroke-linejoin: round;
  --ig-fill: none;
  width: 32px;
  height: 32px;
}

/* Override for a specific context */
.nav icoglyph-svg {
  --ig-stroke: currentColor;
  --ig-stroke-width: 0.3rem;
  width: 20px;
  height: 20px;
}
```

### Hover Effects with --ig-transition


Use --ig-transition to animate CSS properties (opacity, stroke color, etc.) on hover. This is a standard CSS transition value applied to the inner SVG and has no effect on the path morph animation.

```
icoglyph-svg {
  --ig-transition: opacity 0.15s ease;
  cursor: pointer;
}
icoglyph-svg:hover {
  --ig-stroke-opacity: 0.6;
}
```

### Shadow DOM Part


The inner &lt;svg&gt; element is exposed as a CSS part named svg. Use the ::part(svg) pseudo-element to apply styles that CSS custom properties cannot cover, such as filters, transforms, or pointer-events.

```
icoglyph-svg::part(svg) {
  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.15));
}

.interactive icoglyph-svg::part(svg) {
  transition: transform 0.2s ease;
}
.interactive icoglyph-svg:hover::part(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 {
  --ig-stroke: #374151;
  --ig-stroke-width: 0.35rem;
}

.dark icoglyph-svg {
  --ig-stroke: #e5e7eb;
  --ig-stroke-width: 0.35rem;
}

/* Or with media query */
@media (prefers-color-scheme: dark) {
  icoglyph-svg {
    --ig-stroke: #e5e7eb;
  }
}
```

Setting --ig-stroke: currentColor makes the icon inherit the text color of its parent, which is often the simplest way to support themes.

### Responsive Sizing


The component's host element defaults to display: block; width: 100%; height: 100% and fills its parent. If the parent has no explicit size, the icon collapses to zero. Always set a size on the host element itself or on a sized wrapper.

```
/* Fixed size, most common */
icoglyph-svg { width: 48px; height: 48px; }

/* Fill a sized wrapper */
.icon-wrapper { width: 100px; height: 100px; }
.icon-wrapper icoglyph-svg { width: 100%; height: 100%; }

/* Responsive with clamp */
icoglyph-svg { width: clamp(24px, 4vw, 64px); height: clamp(24px, 4vw, 64px); }
```