Skip to content
Nana UI

Data Display & Media

Animated Icon

A motion wrapper around Icon. It renders a real <nana-icon> — inheriting every Heroicon, the shared icon registry and the accessibility wiring — and layers a CSS-driven animation on top, started by a trigger.

View .md Download

Because it composes the existing Icon component, any name you can render with <nana-icon> — including icons you register yourself — works here too. It also honours prefers-reduced-motion: looping motion is suspended, and deliberate hover/click/manual motion is slowed.

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add animated-icon --framework web-components
npx @nana-tec/ui add animated-icon --framework svelte

Lands in src/lib/components/ui/animated-icon/ as NanaAnimatedIcon.svelte, beside the Icon it renders. The frames come from @nana-tec/ui-motion, which the theme already imports.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/animated-icon";

Copied in with npx @nana-tec/ui add animated-icon? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<nana-animated-icon name="cog-6-tooth" animation="spin" trigger="loop"></nana-animated-icon>
<nana-animated-icon name="heart" animation="beat"></nana-animated-icon>
<nana-animated-icon name="bell" animation="shake" trigger="click"></nana-animated-icon>
<script lang="ts">
import { NanaAnimatedIcon } from '$lib/components/ui/animated-icon';
import { arrowPathIcon, bellIcon, cog6ToothIcon } from '@nana-tec/ui-core/heroicons';
let syncing = $state(false);
</script>
<NanaAnimatedIcon icon={cog6ToothIcon} animation="spin" trigger="loop" />
<NanaAnimatedIcon icon={bellIcon} animation="shake" trigger="click" label="Ring" />
<NanaAnimatedIcon icon={arrowPathIcon} animation="spin" trigger="manual" bind:playing={syncing} />

Like Icon, it takes an icon definition, so only the icons you import are bundled. trigger="manual" is driven through bind:playing, or through the play(), pause() and toggle() methods on a bind:this reference. A click run calls onAnimationStart and then onAnimationEnd when its single iteration finishes.

Ten built-in presets. Looping here so the gallery is self-demonstrating.

Control when the animation runs.

<nana-animated-icon name="cog-6-tooth" animation="spin" trigger="loop"></nana-animated-icon>
<nana-animated-icon name="heart" animation="beat" trigger="hover"></nana-animated-icon>
<nana-animated-icon name="bell" animation="tada" trigger="click"></nana-animated-icon>
<nana-animated-icon id="loader" name="arrow-path" animation="spin" trigger="manual"></nana-animated-icon>

Colour follows currentColor and size takes xs to xl; a class sizes it freely. speed picks slow, normal or fast, and --nana-animated-icon-duration sets an exact duration. The frames are the nana-* keyframes in @nana-tec/ui-motion, so a bespoke motion is your own @keyframes applied to [data-part="icon"].

Six ways to make it yours — from a quick colour swap to a fully bespoke animation.

Colour follows currentColor, so set color. Size via the size preset or any font-size.

<nana-animated-icon name="heart" animation="beat"
style="color: var(--nana-color-danger-600);"></nana-animated-icon>
<nana-animated-icon name="cog-6-tooth" animation="spin" size="xl"></nana-animated-icon>
<nana-animated-icon name="cog-6-tooth" animation="spin"
style="font-size: 3rem;"></nana-animated-icon>

Pick a preset with speed, or set an exact duration with --nana-animated-icon-duration.

<nana-animated-icon name="cog-6-tooth" animation="spin" speed="fast"></nana-animated-icon>
<nana-animated-icon name="cog-6-tooth" animation="spin"
style="--nana-animated-icon-duration: 4s;"></nana-animated-icon>

It shares the Icon registry — register an icon once and animate it like any built-in.

import { registerIcons } from "@nana-tec/ui-components";
registerIcons({
pulse: { viewBox: "0 0 24 24", stroke: 1.5, paths: ["M3 12h4l2.25-6 4.5 12L16 12h5"] },
});
<nana-animated-icon name="pulse" animation="float"></nana-animated-icon>

No registration needed for a one-off — drop SVG into the default slot.

<nana-animated-icon animation="spin" trigger="loop">
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor">
<path d="M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z"/>
</svg>
</nana-animated-icon>

Need a motion that isn’t built in? Define your own @keyframes and apply them to the exposed ::part(icon).

<nana-animated-icon class="bell" name="bell"></nana-animated-icon>
@keyframes swing {
20% { transform: rotate(15deg); }
40% { transform: rotate(-10deg); }
60% { transform: rotate(5deg); }
80% { transform: rotate(-5deg); }
100% { transform: rotate(0deg); }
}
.bell::part(icon) {
animation: swing 1s ease-in-out infinite;
transform-origin: top center;
}

It’s just an inline element that inherits colour — slot it into buttons, menus, alerts, anywhere.

<nana-button variant="primary">
<nana-animated-icon name="arrow-path" animation="spin" trigger="hover" slot="prefix"></nana-animated-icon>
Sync
</nana-button>

Properties

PropertyAttributeTypeDefaultDescription
animationanimationAnimatedIconAnimation'pulse'Motion preset
labellabelstring''Accessible label. Leave empty when the icon is decorative.
namenameIconName | ''''Named icon from the built-in set (forwarded to <nana-icon>)
playing—boolean—Whether a click/manual cycle is currently running (reflected as the playing attribute, which the styles key off). Managed as an attribute directly so play() can reliably restart an in-flight animation.
sizesizeSize'md'Size preset
speedspeedAnimatedIconSpeed'normal'Animation speed
triggertriggerAnimatedIconTrigger'hover'What starts the animation

Methods

MethodDescription
pause(): voidStop the animation and reset to the resting frame.
play(): voidStart the animation. Restarts cleanly if one is already running.
toggle(): voidToggle between play() and pause().

Events

EventDescription
nana-animation-startFired when a play cycle begins
nana-animation-endFired when a one-shot (click/manual) cycle ends

Slots

SlotDescription
(default)Custom SVG content (used when name is not set), forwarded to the inner <nana-icon>.

CSS parts

PartDescription
::part(icon)The composed <nana-icon> element

CSS custom properties

PropertyDescription
--nana-animated-icon-durationOverride the animation duration

NanaAnimatedIcon

PropTypeDefault
iconrequiredIconDefinition
labelstring''
sizeSize'md'
animationIconAnimation'pulse'
triggerIconTrigger'hover'
speedIconSpeed'normal'
playingbind:booleanfalse
onAnimationStart() => void
onAnimationEnd() => void

Also accepts Omit<HTMLAttributes<HTMLSpanElement>, 'class'>.