Usage
Variants, triggers, timing and imperative control.
Props
| Prop | Type | Default | Notes |
|---|---|---|---|
variant | per-icon union, e.g. "ring" | "shake" | "jump" | icon's default | Typed per icon |
trigger | "hover" | "auto" | "click" | "inView" | "manual" | "none" | "hover" | inView loops while half the icon is visible; none is static |
hoverTarget | "icon" | "control" | "icon" | control: hovering or keyboard-focusing the surrounding control plays it |
duration | number (ms) | icon's tuning | Absolute: beats speed |
speed | number | 1 | Multiplier on the icon's tuned duration |
interval | number (ms) | 1000 | Rest between loops |
animate | boolean | – | Controlled mode: true loops, false stops |
colors | { primary?, secondary?, accent? } | theme | See Colors |
reducedMotion | "respect" | "ignore" | "always" | "respect" | always stays still regardless of the system setting |
corners | "round" | "bevel" | "sharp" | "round" | Corner geometry, see below |
cornerRadius | number | 2 | How far each corner reaches, in grid units |
size | number | string | 24 | Also settable globally (provider / config.ts); a className size wins |
strokeWidth | number | 2 | In grid units, so it scales with size; also settable globally |
Every other SVG prop (className, style, aria-label, …) is passed through. Icons are decorative
(aria-hidden) unless you give them an aria-label.
Triggers
trigger="hover"trigger="click"trigger="inView"trigger="auto"trigger="manual"<Bell /> // hover: one cycle per pointer enter
<Bell trigger="click" /> // one cycle per click
<Bell trigger="auto" interval={2000} /> // loops from mount, 2s rest between cycles
<Message trigger="inView" /> // loops while on screen
<Bell animate={hasUnread} /> // controlled
<Bell trigger="manual" /> // only plays when you call ref.play()
<Bell trigger="none" /> // static: never animatesnone keeps an icon completely still. Nothing plays it: not hover, not the ref, not animate. Use it for
dense tables, print views, or a "reduce animations" setting in your app. Set it globally (trigger: "none"
in config.ts or on a provider) to freeze every icon, or per icon (icons: { loader: { trigger: "none" } }).
Re-triggering while a cycle is running restarts it from the current pose. The running animations stop where they are and the new cycle starts from there, so a fast hover in-out-in never snaps.
Hovering a parent
Set hoverTarget="control" and the nearest control around the icon plays it: hovering anywhere on a
button, link, menu item, tab or option, or reaching it with the keyboard. A tap on a touch screen doesn't
count as a hover. An icon outside any control falls back to its own hover, and data-icon-control marks
any other element as the control. Set it once on the root provider to make it the app's default:
<AnimatedIconsProvider hoverTarget="control">{children}</AnimatedIconsProvider>
<Button>
<Bell /> Notifications
</Button>For anything else, use trigger="manual" and the ref:
const bell = useRef<AnimatedIconHandle>(null);
<Button onMouseEnter={() => bell.current?.play()}>
<Bell ref={bell} trigger="manual" /> Notifications
</Button>| Method | Does |
|---|---|
play() | One cycle; restarts if one is running. Returns a promise for its end. |
start() | Loop, with interval rest between cycles. |
stop() | Stop looping. The running cycle finishes, so it never freezes mid-pose. |
Timing
speed scales the icon's own tuning and keeps each variant's rhythm. duration sets an absolute
length for one instance:
<Rocket speed={1.5} /> // 50% faster than its tuning
<Rocket duration={1200} /> // exactly 1.2s, whatever the speedCorners
Every icon is drawn from straight segments. At render time, corners reshapes the geometry itself:
each corner between two straight segments becomes a curve, a straight cut, or stays as drawn. Caps
and joins follow.
corners="round"corners="bevel"corners="sharp"corners | Geometry | Caps / joins |
|---|---|---|
round | every corner curved; small squares become dots (default) | round / round |
bevel | every corner cut; small squares become octagons | square / bevel |
sharp | exactly as drawn | square / miter |
cornerRadius (default 2, in 24-grid units) sets how far each corner reaches. A corner never takes
more than half of a side (a third for bevel), so short segments stay intact.
<Bell /> // round, radius 2
<Bell corners="round" cornerRadius={3} /> // softer
<Bell corners="sharp" /> // as drawn
<AnimatedIconsProvider corners="bevel">{/* a whole subtree */}</AnimatedIconsProvider>Stroke width
strokeWidth (default 2) is in the same 24-grid units as the drawing, so a weight looks the same at
every size. Like size, it's yours to set: an icon's own defaults never change it. Widths from 1 to
3 keep every gap in the set open (the slash of a -off icon, a sun behind a cloud).
strokeWidth={1}strokeWidth={1.5}strokeWidth={2}strokeWidth={2.5}strokeWidth={3}<Bell strokeWidth={1.5} /> // lighter
<AnimatedIconsProvider strokeWidth={2.5}>{/* a whole subtree */}</AnimatedIconsProvider>Real curves (a lens, a ring) are left as drawn. Icons that draw inside their own component (for a mask
id, say) shape it with useShapedDrawing().