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.
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.
Preview
Section titled “Preview”<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 { NanaButton } from '$lib/components/ui/button';
import {
arrowPathIcon,
bellIcon,
cog6ToothIcon,
heartIcon,
rocketLaunchIcon,
} from '@nana-tec/ui-core/heroicons';
let syncing = $state(false);
</script>
<div class="flex flex-wrap items-center gap-8 text-foreground">
<NanaAnimatedIcon icon={cog6ToothIcon} animation="spin" trigger="loop" size="lg" />
<NanaAnimatedIcon icon={heartIcon} animation="beat" trigger="hover" size="lg" label="Like" />
<NanaAnimatedIcon icon={bellIcon} animation="shake" trigger="click" size="lg" label="Ring" />
<NanaAnimatedIcon icon={rocketLaunchIcon} animation="float" trigger="loop" size="lg" />
<NanaButton variant="ghost" size="sm" onclick={() => (syncing = !syncing)}>
<NanaAnimatedIcon
icon={arrowPathIcon}
animation="spin"
trigger="manual"
speed="fast"
size="sm"
bind:playing={syncing}
/>
{syncing ? 'Stop sync' : 'Sync'}
</NanaButton>
</div> Installation
Section titled “Installation”npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add animated-icon --framework web-componentsnpx @nana-tec/ui add animated-icon --framework svelteLands 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.
Animations
Section titled “Animations”Ten built-in presets. Looping here so the gallery is self-demonstrating.
<nana-animated-icon
name="cog-6-tooth"
animation="spin"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="arrow-path"
animation="spin-reverse"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="heart"
animation="pulse"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="heart"
animation="beat"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="bell"
animation="bounce"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="bell"
animation="shake"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="pencil-square"
animation="flip"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="trash"
animation="wobble"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="rocket-launch"
animation="float"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="check"
animation="tada"
trigger="loop"
size="lg"
></nana-animated-icon> Triggers
Section titled “Triggers”Control when the animation runs.
<nana-animated-icon
name="cog-6-tooth"
animation="spin"
trigger="loop"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="heart"
animation="beat"
trigger="hover"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="bell"
animation="tada"
trigger="click"
size="lg"
></nana-animated-icon> <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>Customization
Section titled “Customization”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.
1. Colour & size
Section titled “1. Colour & size”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)"
size="lg"
></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> <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>2. Speed & duration
Section titled “2. Speed & duration”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="slow"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="cog-6-tooth"
animation="spin"
speed="normal"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="cog-6-tooth"
animation="spin"
speed="fast"
size="lg"
></nana-animated-icon>
<nana-animated-icon
name="cog-6-tooth"
animation="spin"
style="--nana-animated-icon-duration: 4s"
size="lg"
></nana-animated-icon> <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>3. Your own icons
Section titled “3. Your own icons”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>4. Inline SVG
Section titled “4. Inline SVG”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>5. Bespoke motion
Section titled “5. Bespoke motion”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;}6. Drop into other components
Section titled “6. Drop into other components”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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
animation | animation | AnimatedIconAnimation | 'pulse' | Motion preset |
label | label | string | '' | Accessible label. Leave empty when the icon is decorative. |
name | name | IconName | '' | '' | 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. |
size | size | Size | 'md' | Size preset |
speed | speed | AnimatedIconSpeed | 'normal' | Animation speed |
trigger | trigger | AnimatedIconTrigger | 'hover' | What starts the animation |
Methods
| Method | Description |
|---|---|
pause(): void | Stop the animation and reset to the resting frame. |
play(): void | Start the animation. Restarts cleanly if one is already running. |
toggle(): void | Toggle between play() and pause(). |
Events
| Event | Description |
|---|---|
nana-animation-start | Fired when a play cycle begins |
nana-animation-end | Fired when a one-shot (click/manual) cycle ends |
Slots
| Slot | Description |
|---|---|
(default) | Custom SVG content (used when name is not set), forwarded to the inner <nana-icon>. |
CSS parts
| Part | Description |
|---|---|
::part(icon) | The composed <nana-icon> element |
CSS custom properties
| Property | Description |
|---|---|
--nana-animated-icon-duration | Override the animation duration |
NanaAnimatedIcon
| Prop | Type | Default |
|---|---|---|
iconrequired | IconDefinition | |
label | string | '' |
size | Size | 'md' |
animation | IconAnimation | 'pulse' |
trigger | IconTrigger | 'hover' |
speed | IconSpeed | 'normal' |
playingbind: | boolean | false |
onAnimationStart | () => void | |
onAnimationEnd | () => void |
Also accepts Omit<HTMLAttributes<HTMLSpanElement>, 'class'>.