Animated Icons
docs

Usage

Variants, triggers, timing and imperative control.

Props

PropTypeDefaultNotes
variantper-icon union, e.g. "ring" | "shake" | "jump"icon's defaultTyped 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
durationnumber (ms)icon's tuningAbsolute: beats speed
speednumber1Multiplier on the icon's tuned duration
intervalnumber (ms)1000Rest between loops
animateboolean–Controlled mode: true loops, false stops
colors{ primary?, secondary?, accent? }themeSee Colors
reducedMotion"respect" | "ignore" | "always""respect"always stays still regardless of the system setting
corners"round" | "bevel" | "sharp""round"Corner geometry, see below
cornerRadiusnumber2How far each corner reaches, in grid units
sizenumber | string24Also settable globally (provider / config.ts); a className size wins
strokeWidthnumber2In 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"
Point, click and scroll: these are live.
<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 animates

none 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>
MethodDoes
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 speed

Corners

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"
The same drawing, three ways. Each corner is reshaped at render, not hand-drawn.
cornersGeometryCaps / joins
roundevery corner curved; small squares become dots (default)round / round
bevelevery corner cut; small squares become octagonssquare / bevel
sharpexactly as drawnsquare / 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}
In grid units, so a width scales with the icon's size.
<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().