Lottie Animations and Accessibility: prefers-reduced-motion, ARIA, and Best Practices

@media (prefers-reduced-motion: reduce) {
  /* Pause CSS animations on the SVG */
  .lottie-container svg * {
    animation: none !important;
    transition: none !important;
  }
}

import lottie from 'lottie-web';

const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

const anim = lottie.loadAnimation({
  container: document.getElementById('animation'),
  renderer: 'svg',
  loop: !prefersReducedMotion,
  autoplay: !prefersReducedMotion,
  path: '/animations/hero.json',
});

// If reduced motion: jump to the final frame (show static state)
if (prefersReducedMotion) {
  anim.addEventListener('DOMLoaded', () => {
    anim.goToAndStop(anim.totalFrames - 1, true);
  });
}

import { useState, useEffect } from 'react';

export function useReducedMotion(): boolean {
  const [reducedMotion, setReducedMotion] = useState<boolean>(() => {
    if (typeof window === 'undefined') return false;
    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
  });

  useEffect(() => {
    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');

    function handleChange(e: MediaQueryListEvent) {
      setReducedMotion(e.matches);
    }

    mq.addEventListener('change', handleChange);
    return () => mq.removeEventListener('change', handleChange);
  }, []);

  return reducedMotion;
}

import Lottie from 'lottie-react';
import { useReducedMotion } from './hooks/useReducedMotion';

export function AccessibleAnimation({ animationData }) {
  const reducedMotion = useReducedMotion();

  return (
    <Lottie
      animationData={animationData}
      loop={!reducedMotion}
      autoplay={!reducedMotion}
      // Show static last frame if reduced motion
      initialSegment={reducedMotion ? undefined : undefined}
    />
  );
}

// composables/useReducedMotion.ts
import { ref, onMounted, onUnmounted } from 'vue'

export function useReducedMotion() {
  const reducedMotion = ref(false)

  let mq: MediaQueryList

  onMounted(() => {
    mq = window.matchMedia('(prefers-reduced-motion: reduce)')
    reducedMotion.value = mq.matches

    const handler = (e: MediaQueryListEvent) => {
      reducedMotion.value = e.matches
    }
    mq.addEventListener('change', handler)

    onUnmounted(() => mq.removeEventListener('change', handler))
  })

  return { reducedMotion }
}

<div 
  id="animation"
  aria-hidden="true"
  role="presentation"
></div>

<div aria-hidden="true" style={{ width: 200, height: 200 }}>
  <Lottie animationData={animData} loop autoplay />
</div>

<div
  role="img"
  aria-label="Loading, please wait"
  style={{ width: 48, height: 48 }}
>
  <Lottie animationData={loadingAnim} loop autoplay />
</div>

type Status = 'loading' | 'success' | 'error';

const statusLabels: Record<Status, string> = {
  loading: 'Loading, please wait',
  success: 'Successfully submitted',
  error: 'An error occurred',
};

export function StatusAnimation({ status }: { status: Status }) {
  return (
    <div
      role="status"
      aria-live="polite"
      aria-label={statusLabels[status]}
      style={{ width: 48, height: 48 }}
    >
      {status === 'loading' && <Lottie animationData={loadingAnim} loop autoplay />}
      {status === 'success' && <Lottie animationData={successAnim} loop={false} autoplay />}
      {status === 'error' && <Lottie animationData={errorAnim} loop={false} autoplay />}
    </div>
  );
}

import { useState, useRef } from 'react';
import Lottie, { LottieRefCurrentProps } from 'lottie-react';

export function ControlledAnimation({ animationData }) {
  const [paused, setPaused] = useState(false);
  const lottieRef = useRef<LottieRefCurrentProps>(null);

  function togglePause() {
    if (paused) {
      lottieRef.current?.play();
    } else {
      lottieRef.current?.pause();
    }
    setPaused(!paused);
  }

  return (
    <div>
      <div style={{ width: 300, height: 300 }}>
        <Lottie
          lottieRef={lottieRef}
          animationData={animationData}
          loop
          autoplay
        />
      </div>
      <button
        onClick={togglePause}
        aria-label={paused ? 'Play animation' : 'Pause animation'}
        aria-pressed={paused}
      >
        {paused ? '▶ Play' : '⏸ Pause'}
      </button>
    </div>
  );
}

export function AnimatedButton({ onPress, label }) {
  const lottieRef = useRef(null);

  function handleActivate() {
    lottieRef.current?.stop();
    lottieRef.current?.play();
    onPress?.();
  }

  return (
    <button
      onClick={handleActivate}
      onKeyDown={(e) => {
        if (e.key === 'Enter' || e.key === ' ') {
          handleActivate();
        }
      }}
      aria-label={label}
    >
      <div style={{ width: 24, height: 24 }} aria-hidden="true">
        <Lottie
          lottieRef={lottieRef}
          animationData={iconAnim}
          autoplay={false}
          loop={false}
        />
      </div>
    </button>
  );
}

.animated-button:focus-visible {
  outline: 3px solid #0066cc;
  outline-offset: 2px;
}

import { useRef } from 'react';
import Lottie, { LottieRefCurrentProps } from 'lottie-react';
import { useReducedMotion } from './hooks/useReducedMotion';

interface AccessibleLottieProps {
  animationData: object;
  ariaLabel?: string;
  decorative?: boolean;
  width?: number;
  height?: number;
  loop?: boolean;
}

export function AccessibleLottie({
  animationData,
  ariaLabel,
  decorative = false,
  width = 200,
  height = 200,
  loop = true,
}: AccessibleLottieProps) {
  const reducedMotion = useReducedMotion();
  const lottieRef = useRef<LottieRefCurrentProps>(null);

  return (
    <div
      style={{ width, height }}
      role={decorative ? 'presentation' : 'img'}
      aria-hidden={decorative ? true : undefined}
      aria-label={!decorative ? ariaLabel : undefined}
    >
      <Lottie
        lottieRef={lottieRef}
        animationData={animationData}
        loop={reducedMotion ? false : loop}
        autoplay={!reducedMotion}
      />
    </div>
  );
}

// Decorative (hide from screen readers)
<AccessibleLottie animationData={bgAnim} decorative />

// Meaningful (announce to screen readers)
<AccessibleLottie
  animationData={loadingAnim}
  ariaLabel="Loading, please wait"
  loop
 />