Skip to the content

Motion

Apollion animates with native CSS only: enter transitions run through @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.
Guides

The rule

  • Animate with a motion preset on a component that accepts it — never a hand-written duration.
  • In custom CSS, read the --apollion-motion-* variables with the theme value as the var() 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; use useExitTransition and render data-state.
  • An element that stays mounted and toggles hidden → skip the hook; transition opacity and display with allow-discrete and a @starting-style block.
  • New code reading theme.animation.transitions.* → those are legacy aliases; read theme.motion or the --apollion-motion-* variables.

See also