Motion
@starting-style, exits through a
data-state attribute, and every duration and easing comes from motion tokens. A component declares an
intent such as motion="sheet"; the tokens decide timing, and prefers-reduced-motion decides whether it
moves at all.The rule
- Animate with a
motionpreset on a component that accepts it — never a hand-written duration. - In custom CSS, read the
--apollion-motion-*variables with the theme value as thevar()fallback. - For an element that unmounts, hold it through its exit with
useExitTransition. - Leave reduced motion to the engine: it is global, not per component.
How it works
Tokens. A duration scale (--apollion-motion-duration-150, -300, …), named easings (enter,
exit, emphasized, …) and intents that pair the two: micro, enter, enterFast, exit, exitFast,
emphasis, settle. Each intent exposes a -duration and an -easing variable. The same values live
on theme.motion.
.panel {
transition: transform var(--apollion-motion-intent-emphasis-duration, 300ms)
var(--apollion-motion-intent-emphasis-easing, cubic-bezier(0.2, 0, 0, 1));
}Presets. Surfaces (Paper, Card), Text and the overlays take a motion preset: fade, scale,
slide-up/-down/-left/-right (small nudge), collapse (height to zero), sheet, sheet-top,
drawer-left, drawer-right (full travel from an edge), push-left/push-right (page-level travel for
route swaps) and none. A preset emits the transition, the pre-enter state inside @starting-style and the
exit state under [data-state="closing"]. Box, Flex and Grid are layout-only and take no motion.
import { Paper } from '@apollion-dsi/core/containers/paper';
import { useExitTransition } from '@apollion-dsi/core/hooks';
function Panel({ open }: { open: boolean }) {
const { mounted, state, ref } = useExitTransition(open);
if (!mounted) return null;
return (
<Paper ref={ref} motion="sheet" data-state={state} p="large">
Panel content
</Paper>
);
}Built-in defaults. Overlays animate with no client code. Dropdown, Tooltip, Popover and the
InputDate calendar grow out of their anchor (scale) and shrink on exit; the InputSelect menu enters
with scale. motion="none" opts any of them out. Modal and Sheet pair an overlay fade with a
sheet or drawer; a stacked Notification toast leaves with collapse, so the toasts below reflow with
no measurement; Accordion panels use the collapse recipe.
Reduced motion. Under prefers-reduced-motion: reduce one global rule sets every duration variable
to 0.01ms. The indicator channel (--apollion-motion-indicator-loop/-pulse, used by Spinner and
StatusDot) is exempt, because a near-zero infinite cycle would strobe. push-left/push-right swap
their travel for fade.
View transitions. For page-level cross-fades, extend GlobalStyle with viewTransitionStyles from
@apollion-dsi/core/themes/motion and wrap the state change in document.startViewTransition where it
exists. Old frames leave on the exit intent and new ones arrive on enter; browsers without the API swap
instantly.
Pitfalls
- Unmounting on close (
open && <Paper motion="sheet" />) → the exit never plays; useuseExitTransitionand renderdata-state. - An element that stays mounted and toggles
hidden→ skip the hook; transitionopacityanddisplaywithallow-discreteand a@starting-styleblock. - New code reading
theme.animation.transitions.*→ those are legacy aliases; readtheme.motionor the--apollion-motion-*variables.