Presets and options
Thirteen presets are public at 0.x. Each one is defined by what it communicates, mirroring the SF Symbols vocabulary, and the engine chooses per-layer motion from the icon's composition and salience tiers. Pass a preset key as effect, or { name, options } to tune it.
| Preset | Kind | Communicates | Requires |
|---|---|---|---|
appear public | entry (settles visible) | an element being introduced into view | — |
disappear public | exit (settles hidden) | an element being removed from view | — |
drawOn public | entry (settles visible) | being drawn into being (handwriting); progress | a stroke layer |
drawOff public | exit (settles hidden) | being un-drawn / erased / undone | a stroke layer |
metaphorical public | one-shot (settles) | the icon's own signature meaning, enacted | an authored icon or layer metaphor |
bounce public | one-shot (settles) | an action occurred or needs to take place | — |
wiggle public | one-shot (settles) | a change or call to action a person might overlook | — |
rotate public | one-shot (settles) | a task in progress / real-world rotation | — |
pulse public | loop (indefinite; gate with isActive) | ongoing activity until a condition is met | — |
breathe public | loop (indefinite; gate with isActive) | a living, present, ongoing state | — |
scale public | one-shot (settles) | selection focus / pressed feedback, held | — |
variableColor public | value-driven | progress, strength, or connecting — a sequence of stages | variable-step layers (signal bars, Wi-Fi arcs, …) |
progress public | value-driven | a value advancing along a path | a variableValueBehavior on the icon |
replace experimental | transition between two icons | a shift in functionality / the next available action | a family mapping between the two icons; out of the public contract at 0.x (type kept, no docs, no Lottie export) |
Options
Every option is optional. An option a preset does not read is ignored rather than rejected, so a spec built from a runtime string still type-checks. The per-preset scorecard (pnpm scorecard) measures whether each option actually changes the engine output; on this branch all 61 applicable contracts hold.
| Option | Type | Honoured by | Notes |
|---|---|---|---|
scope | "wholeSymbol" | "byLayer" | "individually" | all except progress | byLayer staggers along the composition's spatial order; individually plays one layer at a time. |
direction | up | down | left | right | center | up-left … | cw | ccw | preferred | appear, metaphorical, bounce, wiggle, scale (up/down), rotate (cw/ccw/preferred) | Directions a preset does not read are inert, not errors. |
angle | number (degrees) | wiggle | Custom wiggle axis. |
repeat | number | "infinite" | one-shots and loops | Loops are already indefinite; use isActive to stop them. |
repeatDelay | number (ms) | repeating one-shots | Rest at the settled pose between plays. |
speed | number (multiplier) | all time-driven presets | Timing only. Scorecard: speedHonored 100% where applicable. |
intensity | number 0–2 | appear, disappear, metaphorical, bounce, wiggle, pulse, breathe, scale | Magnitude, not timing. Inert on visibility-only presets (drawOn/Off, variableColor) and on rotate, whose angle defines the endpoint. |
frequency | number | wiggle, pulse, breathe, variableColor | Loop rate. |
value | number 0–1 | variableColor, progress | Runtime datum; also the `value` prop. |
reversing | boolean | variableColor | Ping-pong instead of wrap. |
inactive | "dim" | "hide" | variableColor | Treatment of unlit steps. |
style | "plain" | "pulse" | breathe | Deepens the opacity component. |
delay | number (ms) | all | Start offset. |
spring | { stiffness?, damping? } | spring-driven presets | Overrides the config palette for one invocation. |
amplitude, decay, hold, easing, max | various | preset-specific | Editor-grade tuning knobs; documented in the API reference. |
Weight
weight is a number: the stroke width in viewBox units on the 24-unit grid. Omitted, it follows the size curve (DEFAULT_WEIGHT_CURVE): 1.25 at 16 px, 1.5 at 24 px, 2.0 at 48 px. Strokes scale with the rendered size (weight × size ÷ 24 CSS px), matching Hugeicons. Named weights are an internal convenience of this demo and are not part of the public API.
Rendering mode
Icons render monochrome: every layer paints with currentColor, so an icon takes the colour of the text around it. renderingMode="monochrome" (the default) is the only supported value at 0.x — multi-tone rendering is not part of this release on any platform.