@dloizides/ui-motion

Themable, brand-agnostic React Native (RN-web) motion primitives — the shared animation layer of the dloizides.com UI kit.

• Built on RN Animated only. No reanimated / moti / framer.
• Native driver on native, JS driver on web (useNativeDriver: Platform.OS !== 'web').
• Every animation collapses to instant when the user prefers reduced motion (useReducedMotion(), re-exported from @dloizides/rn-web-hooks).
• Motion values (durations + easings) come from @dloizides/design-tokens, so web (CSS cubic-bezier) and native (Easing.bezier) animate on the same curves.

Install

npm install @dloizides/ui-motion

Peer deps: react >=18, react-native >=0.74. Runtime deps @dloizides/design-tokens and @dloizides/rn-web-hooks are installed automatically.

Tokens

import { motionDurations, motionEasings, DEFAULT_MOTION } from '@dloizides/ui-motion';

motionDurations; // { instant: 0, fast: 140, base: 200, slow: 300 } (ms)
motionEasings.standard;   // RN EasingFunction built from cubic-bezier(0.2,0,0,1)
motionEasings.decelerate; // entering elements
motionEasings.accelerate; // leaving elements
DEFAULT_MOTION.easings.standard.css; // 'cubic-bezier(0.2,0,0,1)' for web/CSS consumers

Hooks

useReducedMotion() / prefersReducedMotion()

Re-exported from @dloizides/rn-web-hooks (the canonical gate — not forked). Web reads matchMedia('(prefers-reduced-motion: reduce)'); native returns false.

useEnterExit({ visible, duration?, translateY?, fromScale? })

The reusable enter/exit pattern (fade + optional translate/scale) promoted from ui-feedback's ToastHost. Returns an animated style and a mounted flag so the node stays in the tree until its exit animation finishes.

const { style, mounted } = useEnterExit({ visible: open, translateY: -6 });
if (!mounted) return null;
return <Animated.View style={style}>{children}</Animated.View>;

useFocusLift(focused, spring, { scale?, lift? })

Springs a tile to scale (default 1.06) and -lift px (default 8) while focused, back to rest otherwise. A focus change retargets the running spring. Reduced motion: no movement (signal focus with a ring/shadow instead). Spread style onto an Animated.View. Pure target: focusLiftTarget.

useSequence(items, { totalMs, itemMs?, playKey?, playOnMount? })

Staggers along any ordered list inside a fixed total: the last item ends at totalMs however long the list is. progressAt(index) is a 0-1 animated value for that item, built on demand. A new playKey replays from the first item; playOnMount: false starts final and waits for one. Reduced motion: every item is final at once. Input is never blocked: no interaction handle, nothing to await. Pure timing: sequenceItemRange.

Components

<ScreenTransition transitionKey duration? easing? testID?>

Slides its children in from the right by one window width when transitionKey changes; the first render does not animate. Defaults: motionDurations.slow, motionEasings.decelerate. Reduced motion cuts straight to the content. Router-agnostic: pass the pathname as the key.

<ScreenTransition transitionKey={usePathname()}>
  <Stack screenOptions={{ animation: 'none' }} />
</ScreenTransition>

<FadeIn duration? delay? translateY? style? testID>

Fades (and slightly lifts) its children in once, on mount.

<FadeIn><Card /></FadeIn>

<Collapse open duration? style? testID>

Animated height expand/collapse that works on web — it measures the content's natural height and animates a real Animated.Value height (unlike LayoutAnimation, a native-only no-op on RN-web). Children stay mounted; overflow is clipped.

<Collapse open={expanded}><Details /></Collapse>

<PressableScale pressedScale? innerStyle? ...PressableProps>

A Pressable that scales down (default 0.96) on press-in and springs back on press-out. Forwards all Pressable props and accessibility. Designed to replace bare activeOpacity in @dloizides/ui-buttons.

<PressableScale accessibilityLabel="Save" accessibilityHint="Saves the form" onPress={save}>
  <Text>Save</Text>
</PressableScale>

<Skeleton width? height? borderRadius? duration? backgroundColor? highlightColor? style? testID>

A rounded placeholder block with a highlight band that sweeps across it — a stronger loading signal than the opacity pulse in ui-feedback's PageSkeleton.

<Skeleton width="60%" height={20} borderRadius={6} />

<Reorder itemKeys spring staggerMs? cap? testID>{(key) => node}</Reorder>

FLIP re-rank for a keyed list: when itemKeys changes order, moved items spring from their old slot to the new one, staggered (default 18ms), at most cap (default 8) animated. Under reduced motion items jump. The invert maths is the pure computeFlipDeltas.

Reduced motion

Every primitive honours the OS "reduce motion" setting: FadeIn shows content at rest, Collapse snaps to the target height, PressableScale keeps scale 1, Skeleton shows a static block, and useEnterExit collapses its duration to 0.

Testing philosophy

Unit tests cover logic (reduced-motion collapse, mount/exit lifecycle, token derivation, prop forwarding), not animation frames — the frame-driven paths are verified in the app E2E suites.

License

MIT © dloizides

HairlineFigure (@dloizides/ui-motion/hairline)

Wraps @lucasmarkes/[email protected] (exact pin) so apps never import it directly. Props: figure (HairlineFigureName), colors (a ModeColors from @dloizides/design-tokens, mapped onto --hairline-* by hairlineVars), intensity (0-1), label (translated), testID.

• Web (RN-web, browser condition): mounts the vanilla API on the View's DOM node; destroyed on unmount.
• Native (react-native condition): renders the upstream bundle inlined as HTML in react-native-webview (optional peer; install it to use this subpath on iOS/Android). One figure per screen.
• A figure is decoration: never put information a user needs in it. On touch-first screens prefer horizontal/area figures (terrain, riffle, keyboard, router, rail, dish, turntable, plot).

Logo player (@dloizides/ui-motion/logo)

Framework-free (no React in its import graph; only @dloizides/design-tokens), for plain HTML pages and vanilla Vite apps. The mark is drawn elsewhere; name its parts with data-motion-layer="<name>".

import { playLogo, bindMicro, type LogoTimeline } from '@dloizides/ui-motion/logo';

const intro: LogoTimeline = [
  { layer: 'sheet', keyframes: [{ opacity: 0, transform: 'translateY(6px)' }, { opacity: 1, transform: 'none' }], duration: 'slow', easing: 'decelerate' },
  { layer: 'fold', keyframes: [{ opacity: 0 }, { opacity: 1 }], duration: 'base', delay: 160 },
];
const { finished, cancel } = playLogo(svg, intro);
const unbind = bindMicro(svg, pulse, 'hover');

• playLogo(svg, timeline, { reducedMotion?, iterations? }) => { finished, cancel }: one WAAPI animation per matching layer, fill: 'both'; finished resolves on completion or cancel.
• Beat: { layer, keyframes, duration: 'instant'|'fast'|'base'|'slow'|ms, easing?: 'standard'|'decelerate'|'accelerate', delay?: ms }, resolved from DEFAULT_MOTION.
• Reduced motion (option, else prefers-reduced-motion) or no WAAPI: the last keyframe is applied at once, no animation.
• bindMicro(svg, timeline, 'hover'|'focus'|'loading', { reducedMotion? }) => unbind: hover = pointerenter/leave, focus = focusin/out, loading = loops until unbind; nothing under reduced motion.
• Beat required: true: if the mark has no node for that layer, playLogo applies the final frames and starts no animation.

Presets

import { bindMicro, logoPreset, playLogo } from '@dloizides/ui-motion/logo';

playLogo(svg, logoPreset(config.logoAnimation));
bindMicro(svg, logoPreset(config.logoAnimation, { cut: 'micro' }), 'hover');

logoPreset(name?, { cut? }) returns a LogoTimeline. Names: line-draw (default), day-sweep, orbit-lock, fold (LOGO_PRESET_NAMES); an unknown name returns the default. Cuts: intro (default, up to 1.2 s), sting (3.6 s: 300 ms hold, the intro stretched, 500 ms hold), micro (up to 300 ms, starts and ends on the still). No preset animates CSS d.

| data-motion-layer | Role | Needed by | |---|---|---| | emblem | Main shape | line-draw, day-sweep, orbit-lock | | part-1, part-2, part-3 | Secondary shapes; several nodes may share a name | fold | | ghost | Dim copy behind the emblem, absent from the still (author it with opacity="0") | none |

A mark missing a needed layer shows its still. The mark's own markup supplies the rest:

• line-draw: filled shapes with pathLength="1" and no stroke in the still.
• orbit-lock, fold: CSS transform-box: view-box and transform-origin on each layer: the orbit centre for emblem, the point the parts meet for part-*.
• Optional CSS variables: --logo-line, --logo-line-width (viewBox units, default 1.5px), --logo-accent; colours fall back to currentColor.