# Animation
Every part of a component exposes its state as a data attribute, and parts are plain DOM elements. That leaves the animation up to you: a CSS transition, a keyframe animation or a JavaScript library all work, and the patterns below show how a few common cases fit together.
## CSS transitions
A part that opens carries `data-state="open"` or `data-state="closed"`. Transition between the two and most enter and exit animations need no JavaScript:
```css
[data-popover-content] {
transform-origin: var(--transform-origin);
transition:
opacity 250ms,
scale 250ms,
display 250ms allow-discrete;
&[data-state='closed'] {
opacity: 0;
}
@starting-style {
&[data-state='open'] {
opacity: 0;
}
}
@media (prefers-reduced-motion: no-preference) {
&[data-state='closed'] {
scale: 0.95;
}
@starting-style {
&[data-state='open'] {
scale: 0.95;
}
}
}
}
```
Two CSS features make this work for parts that are hidden while closed:
- [`@starting-style`](https://developer.mozilla.org/en-US/docs/Web/CSS/@starting-style) gives a part the style to transition from on the frame it appears.
- [`transition-behavior: allow-discrete`](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-behavior) lets `display` take part in the transition. Fluid Primitives sets the `hidden` attribute as soon as a part closes, and `allow-discrete` postpones it until the exit has played.
> **Quick Tip** - Use transitions over animation keyframes because they are interruptible.
### Scale from the trigger
Popover, Menu, Select, Combobox, Tooltip and DatePicker set `--transform-origin` on their positioner to the point closest to the trigger. Pick a side and open the popover.
**AnimationExamples.html**
```html
TopRightBottomLeft
Delivery options
Delivery optionsChoose standard or express shipping at checkout.
```
**PopoverPlacement.entry.ts**
```ts
import { mount } from 'fluid-primitives';
import { Popover } from 'fluid-primitives/popover';
import { ToggleGroup } from 'fluid-primitives/toggle-group';
const popover = mount('primitives:popover', 'placement-popover', ({ props }) =>
new Popover(props).init()
);
mount('ui:toggleGroup', 'placement-group', ({ props }) =>
new ToggleGroup({
...props,
onValueChange: ({ value }) =>
popover?.updateProps({
positioning: {
gutter: 8,
placement: value[0] as 'top' | 'right' | 'bottom' | 'left',
},
}),
}).init()
);
```
### Swap an indicator
A pressed Toggle carries `data-pressed`. Two icons in one grid cell and a `group-data-[pressed]:` variant crossfade the icons, here with a short blur and scale.
**AnimationExamples.html**
```html
```
**ToggleIcon.entry.ts**
```ts
import { mountAll } from 'fluid-primitives';
import { Toggle } from 'fluid-primitives/toggle';
mountAll('primitives:toggle', ({ props }) => new Toggle(props).init());
```
Collapsible and Button indicators switch with the `hidden` attribute, so they use the same two features as a part that opens: `starting:` styles the indicator that appears and a `[&[hidden]]:` rule styles the one that leaves.
**AnimationExamples.html**
```html
Shipping details
Orders ship within 2 working days. Delivery takes 2 to 3 days inside Germany.
```
## JavaScript
CSS cannot animate everything. A list that changes its columns, an element that moves to another parent or a button that changes its width have no CSS transition to reach for. For these, hand the work to an animation library. The examples below use [Motion](https://motion.dev), and the same approach works with any library that animates DOM elements: the callbacks of a component (`onOpenChange`, `onValueChange`, ...) tell you when to start.
```bash
npm install motion
```
### Animate a layout change
Motion's `animateLayout` measures elements before and after a DOM change and animates the difference. Mark the elements with `data-layout` and make the change inside the callback:
```ts
import { animateLayout } from 'motion';
animateLayout(list, () => (list.dataset.view = 'list'), {
type: 'spring',
duration: 0.4,
bounce: 0,
});
```
**AnimationExamples.html**
```html
GridList
{product.name}
{product.price}
```
**LayoutView.entry.ts**
```ts
import { mount, mountAll } from 'fluid-primitives';
import { ToggleGroup } from 'fluid-primitives/toggle-group';
import { animateLayout } from 'motion';
const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
mountAll('ui:animationExamples.layoutView', ({ props, createHydrator }) => {
const products = createHydrator().query('products');
if (!products) return;
mount('ui:toggleGroup', `${props.id}-view`, ({ props }) =>
new ToggleGroup({
...props,
onValueChange: ({ value }) => {
animateLayout(
products,
() => (products.dataset.view = value[0]),
reduceMotion.matches
? { duration: 0 }
: { type: 'spring', duration: 0.4, bounce: 0 }
);
},
}).init()
);
});
```
- `data-layout` on a child keeps its proportions while the parent resizes. `data-layout="position"` moves a child without resizing it, which suits text.
- The scale of a box stretches its border and corners while it animates. The product images are square in both views and the rows have no surface, so nothing looks stretched.
> **Transitions on transform** - Motion writes `transform` on every frame. A CSS transition that includes it, like Tailwind's `transition-all`, works against it, so list the properties you transition.
### Move an element into a dialog
An element that moves to another parent animates from its old box to the new one. Here the whole card moves into the dialog and grows, while the image, title and price settle into their new places and the description fades in. The dialog panel stays still and the card brings its own background, so Motion measures the card where it lands.
On its way back the card stays in the layer of the dialog and flies to a fixed position over its button, so it never passes below the backdrop. Once it has landed, it moves back into the list.
**AnimationExamples.html**
```html
Close
```
**ProductCards.entry.ts**
```ts
import { mount, mountAll } from 'fluid-primitives';
import { Dialog } from 'fluid-primitives/dialog';
import { animateLayout } from 'motion';
// Seconds, shared by the layout and the colour transition of the card.
const duration = 0.4;
mountAll('ui:animationExamples.productCards', ({ props, createHydrator }) => {
const hydrator = createHydrator();
const slot = hydrator.query('slot');
const extras = hydrator.query('extras');
const description = hydrator.query('description');
const content = slot?.parentElement;
const positioner = content?.parentElement;
if (!slot || !extras || !description || !content || !positioner) return;
let current: { button: HTMLElement; card: HTMLElement } | null = null;
let landing: (() => void) | null = null;
let timer: number | undefined;
// The same elements move between the grid and the dialog, so the layout animation flies them over.
const move = (update: () => void, done?: () => void) =>
animateLayout(
update,
matchMedia('(prefers-reduced-motion: reduce)').matches
? { duration: 0 }
: { type: 'spring', duration, bounce: 0 }
).then(animation => animation.finished.then(done));
const open = () => {
if (!current) return;
const { button, card } = current;
// A card that is still flying back lands in its list first, then this one lifts off.
landing?.();
move(() => {
button.style.height = `${button.offsetHeight}px`;
card.toggleAttribute('data-expanded', true);
slot.append(card);
card.append(extras);
description.textContent = button.dataset.description ?? '';
content.ariaLabel = card.querySelector('[data-title]')?.textContent ?? null;
});
};
// The card stays in the dialog layer and flies to the place of its button there, so it never
// passes below the backdrop. Only after it has landed it moves back into the list.
const close = () => {
if (!current) return;
const { button, card } = current;
const land = () => {
Object.assign(card.style, { position: '', top: '', left: '', width: '' });
button.append(card);
button.style.height = '';
if (landing === land) landing = null;
};
landing = land;
move(
() => {
const { top, left, width } = button.getBoundingClientRect();
card.toggleAttribute('data-expanded', false);
slot.after(extras);
positioner.append(card);
Object.assign(card.style, {
position: 'fixed',
top: `${top}px`,
left: `${left}px`,
width: `${width}px`,
});
},
// A newer move has taken over when `landing` is not this one any more.
() => landing === land && land()
);
};
mount('ui:dialog', `${props.id}-dialog`, ({ props }) =>
new Dialog({
...props,
// The dialog knows which of its triggers is active, so the card needs no click listener.
onTriggerValueChange: ({ triggerElement: button }) => {
const card = button?.querySelector('[data-card]');
current = button && card ? { button, card } : null;
card?.style.setProperty('--duration', `${duration}s`);
},
onOpenChange: ({ open: isOpen }) => {
clearTimeout(timer);
// The description and the button fade out first, then the card flies back.
// Zag sets the active trigger right after this callback, so the card is known one microtask later.
if (isOpen) queueMicrotask(open);
else timer = window.setTimeout(close, 100);
},
}).init()
);
});
```
### Animate a button's width and label
A width cannot transition between two `auto` values, so a button whose label changes length jumps. The three labels are in the markup and `data-status` decides which one is displayed. They enter and leave with the `@starting-style` and `allow-discrete` pair from above, and `justify-center` keeps them in the middle of the button while it resizes. Motion only animates the width: the script reads it before and after the status change and springs between the two.
**AnimationExamples.html**
```html
Send me a login link
Sending
Login link sent!
```
**LoginLinkButton.entry.ts**
```ts
import { mount, mountAll } from 'fluid-primitives';
import { Button } from 'fluid-primitives/button';
import { animate } from 'motion';
type Status = 'idle' | 'loading' | 'success';
mountAll('ui:animationExamples.loginLinkButton', ({ props }) => {
const button = mount('ui:button', `${props.id}-button`, ({ props }) =>
new Button(props).init()
);
const root = button?.hydrator.query('root');
if (!button || !root) return;
// A width cannot transition between two `auto` values, so Motion animates it from the old to the new width.
const show = (status: Status) => {
const from = root.getBoundingClientRect().width;
root.dataset.status = status;
const to = root.getBoundingClientRect().width;
if (from === to || matchMedia('(prefers-reduced-motion: reduce)').matches) return;
// Pinned before the next paint, so no frame shows the new width early.
root.style.width = `${from}px`;
animate(0, 1, {
type: 'spring',
duration: 0.3,
bounce: 0,
onUpdate: progress => (root.style.width = `${from + (to - from) * progress}px`),
onComplete: () => root.style.removeProperty('width'),
});
};
let status: Status = 'idle';
button.api.addEventListener('click', () => {
if (status !== 'idle') return;
status = 'loading';
button.api.setLoading(true);
show('loading');
setTimeout(() => {
status = 'success';
button.api.setLoading(false);
show('success');
}, 1750);
setTimeout(() => {
status = 'idle';
show('idle');
}, 3500);
});
});
```