Codectionary / Developer documentation / CSS

prefers-color-scheme & prefers-reduced-motion

These media queries detect user system preferences rather than device characteristics. prefers-color-scheme detects whether the user has requested a light or dark theme at the OS level. prefers-reduced-motion detects whether the user has requested minimal animation, important for users with vestibular motion sensitivity.

Syntax

@media (prefers-color-scheme: dark) { }
@media (prefers-reduced-motion: reduce) { }

Examples

Automatic Dark Mode

Respecting the user's OS-level theme preference without needing a toggle.

:root {
  --bg-color: white;
  --text-color: black;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg-color: #1a1a1a;
    --text-color: #f0f0f0;
  }
}

body {
  background: var(--bg-color);
  color: var(--text-color);
}
  1. The browser preference chooses which custom-property values apply.
  2. The documentation theme switch and the operating-system preference are separate signals.
  3. Use DevTools media emulation or change the system preference to compare light and dark states.
HTML used by this example
<article><h3>Preference-aware reading view</h3><p>The preview follows the browser’s colour-scheme preference.</p></article>

Respecting Reduced Motion

Disabling or simplifying animations for users who have requested reduced motion.

/* Demo setup: sizing, structure or neutral surfaces. */
@keyframes fadeInUp{from{opacity:0;transform:translateY(20px)}to{opacity:1;transform:translateY(0)}}.card{padding:1rem;border:1px solid #94a3b8}

.card {
  animation: fadeInUp 0.5s ease-out;
}

@media (prefers-reduced-motion: reduce) {
  .card {
    animation: none; /* or a much shorter, simpler transition */
  }
}
  1. The setup includes the keyframes referenced by the original snippet.
  2. The preference query removes the animation for reduced-motion users.
  3. A one-shot entrance may finish quickly; run again or inspect animation-name under each emulated preference.
HTML used by this example
<article class="card"><h3>A motion-aware announcement</h3><p>Replay the example, then emulate reduced motion.</p></article>

Parameters and values

  • prefers-color-scheme (light | dark): Detects the user's OS-level theme preference
  • prefers-reduced-motion (no-preference | reduce): Detects whether the user has requested minimal animation

Best practices

  • Support prefers-color-scheme as a baseline even in projects with a manual theme toggle, so the OS preference is respected on first visit
  • Always wrap meaningful animations and auto-playing effects in a prefers-reduced-motion check - this genuinely matters for users with vestibular disorders
  • Test both preferences using actual OS/browser settings, not just guessing, since behavior can be easy to overlook without deliberately checking
  • Combine both queries with custom properties for a clean, maintainable way to swap entire sets of values based on user preference

Browser compatibility

chrome
Yes
firefox
Yes
safari
Yes
edge
Yes

These are the existing reference’s support labels, not tested minimum versions. Individual values and APIs can have different support. Check the linked specification before choosing a browser target.

CSS specifications (modules)

Specifications & further reading