@open-symbols/core

The platform-independent heart of Open Symbols: a pure-math animation engine, the icon schema, and 2,000 layer-tagged icons (derived from Hugeicons).

(icon, effect, config, state) → RenderInstruction[]

The engine reads no clock and touches no DOM, so the same frame can be computed on a server, in a test, in a browser adapter or in a native port. React users normally install @open-symbols/react and only import icons from here; without React use @open-symbols/dom (mountIcon) or the <open-symbol> custom element.

0.x — not yet stable. Minor releases may change APIs and icon motion. See versioning.

Install

npm install @open-symbols/core

ESM only. Node ≥ 18.18, evergreen browsers, TypeScript ≥ 5.0.

Entry points

| Import | What | Size (min + gzip) | |---|---|---| | @open-symbols/core/icons/<slug> | one resolved IconDefinition (default export) | ~1.5 KB | | @open-symbols/core/engine + /config | createEngine, DEFAULT_CONFIG | 13.8 KB | | @open-symbols/core/spring | closed-form spring solver | 0.3 KB | | @open-symbols/core/registry | registerIcons, getRegisteredIcon, createIconRegistry | < 0.3 KB | | @open-symbols/core/runtime | everything an adapter needs, no catalog | tree-shaken | | @open-symbols/core/contract | PUBLIC_PRESETS, ICON_SCHEMA_VERSION, ResolvedIconDefinition | tiny | | @open-symbols/core/loader | fetchIcon from the JSON CDN | tiny | | @open-symbols/core/icons | the bundled catalog: getIcon, listIcons, listIconMeta, resolveIconName | ~630 KB | | @open-symbols/core/icons/all | registers the whole catalog into the shared registry | ~630 KB | | @open-symbols/core | runtime + catalog accessors (tree-shakes: springAt alone stays < 1 KB) | — |

Sizes are measured in CI with esbuild; "twenty icons + engine + registry" is 22.1 KB.

Compute a frame

import { createEngine } from "@open-symbols/core/engine";
import { DEFAULT_CONFIG } from "@open-symbols/core/config";
import wifi from "@open-symbols/core/icons/wifi01";

const engine = createEngine();
const frame = engine.compute(wifi, { name: "appear" }, DEFAULT_CONFIG, {
  elapsedMs: 137,
  reducedMotion: false,
});
frame.instructions; // one RenderInstruction per layer
frame.settled;      // true once the effect has come to rest

RenderInstruction fields and units are specified in API reference; effect options and which presets honour them in presets and options.

Icons

Every icon is a resolved IconDefinition: the generated artwork with every hand correction, motion tier and color tier applied. Two public metadata fields:

• quality: "reviewed" when a human-verified audit covers the icon's grouping, motion hierarchy and color tiers; "provisional" otherwise. Today 685 of 2,000 icons are reviewed. Provisional icons are shipped and usable; their motion may still be corrected in a later 0.x release.
• aliases: former slugs that still resolve to the icon (20 today, e.g. heart → favourite). Registries and getIcon accept them. Runtime definitions omit the field when there are none; the published JSON (ResolvedIconDefinition, toResolvedIcon) always carries an array.

Load icons at runtime

The same resolved JSON is published as @open-symbols/icons, so any npm CDN serves it immutably per version:

import { fetchIcon } from "@open-symbols/core/loader";

const icon = await fetchIcon("wifi01", { version: "0.1.0" });
// https://cdn.jsdelivr.net/npm/@open-symbols/[email protected]/icons/wifi01.json

fetchIcon checks the package's manifest.json schemaVersion once per base URL, validates the response and registers the icon (pass register: false to skip). Pin version (or pass baseUrl for a self-hosted copy); unpinned URLs are rejected.

Public presets (0.x)

appear, disappear, drawOn, drawOff, bounce, wiggle, scale, pulse, breathe, rotate, variableColor, progress, metaphorical (PUBLIC_PRESETS). The replace preset is experimental and outside the stability promise. Rendering is monochrome for this release; duotone is parked, with its internal code and type fields retained for future development.

weight is a number: stroke width in the 24-unit viewBox. The adapters fill an omitted weight from DEFAULT_WEIGHT_CURVE (1.25 at 16 px, 1.5 at 24 px, 2.0 at 48 px). Strokes scale with the rendered size.

Reduced motion

Pass reducedMotion: true in the engine state and every preset resolves to a settled pose or a short opacity crossfade; no preset moves.

License

MIT for the code. The icon artwork is derived from @hugeicons/core-free-icons 4.1.1 (MIT); keep THIRD_PARTY_NOTICES with any redistribution. Open Symbols is not affiliated with Apple.