useReducedMotion

The useReducedMotion hook detects whether animations should be disabled based on the user's prefers-reduced-motion system setting and low-end device hardware (CPU cores, device memory). It returns a shouldAnimate flag that components use to automatically skip or simplify animations.

Used in components: Mask, ParticleFx, TiltFx, HoloFx, MatrixFx, WeatherFx, CelebrationFx, ShineFx

All effect components use this hook internally with a reducedMotion prop defaulting to 'auto'. You only need this hook directly when building custom animated components.

Features

Detects prefers-reduced-motion: reduce media query
Detects low-end devices (≤2 CPU cores or ≤2GB memory)
Reactive — updates when the user changes their system setting
Override support: force animations on or off regardless of detection
SSR-safe — returns safe defaults on the server

Basic usage

Use the hook to conditionally run animations:

Basic

import { useReducedMotion } from "@once-ui-system/core";

function MyComponent() {
  const { shouldAnimate } = useReducedMotion();

  useEffect(() => {
      if (!shouldAnimate) return;
      // Start animation loop
  }, [shouldAnimate]);
}

Override

Pass true to force reduced motion (disable animations), false to force full animations, or "auto" (default) to detect automatically.

Override

// Auto-detect (default)
const { shouldAnimate } = useReducedMotion("auto");

// Force animations off
useReducedMotion(true);

// Force animations on
useReducedMotion(false);

Return value

	Type	Default
prefersReducedMotion	boolean	—
isLowEnd	boolean	—
shouldAnimate	boolean	—

API reference

	Type	Default
override	truefalse"auto"	"auto"

Hardware detection

The hook checks two signals to determine low-end devices:

navigator.hardwareConcurrency — number of CPU cores (≤2 = low-end)
navigator.deviceMemory — device memory in GB (≤2 = low-end, Chrome/Edge only)

These checks run once on mount and do not change during the session.