browser-reduced-motion

Reactive (prefers-reduced-motion: reduce) as a read-only external atom plus a boolean selector.

Install

bun add @valdres/browser-reduced-motion

Live example

▶ Live example: https://valdres.dev/react/plugins/browser-reduced-motion

Usage

Every read works through a store, with no adapter at all:

import { store } from "valdres"
import { reducedMotionAtom, prefersReducedMotionSelector } from "@valdres/browser-reduced-motion"

const app = store()
app.get(reducedMotionAtom) // "no-preference" | "reduce" — reads without subscribing
app.get(prefersReducedMotionSelector) // boolean
const stop = app.sub(reducedMotionAtom, () => {
    console.log(app.get(reducedMotionAtom))
})
stop()

import { useValue } from "valdres-react"
import { prefersReducedMotionSelector } from "@valdres/browser-reduced-motion"

function Banner() {
    const reduced = useValue(prefersReducedMotionSelector)
    return <div className={reduced ? "static" : "animated"} />
}

Adapter support in this beta

valdres-react is the only adapter migrated to the v1 core. The Vue, Svelte, Solid and Angular adapters cannot read an external atom yet: valdres-vue's useValue and valdres-angular's injectValue are typed for Atom | Selector only, valdres-solid's createValue still expects the pre-v1 two-parameter State, and valdres-svelte exports fromState, not the watch these pages used to show. Until those adapters ship, read this package with store.get / store.sub as above.

Exports

| Export | Kind | Type | | ------------------------------ | ------------------------- | ----------------------------------------------- | | reducedMotionAtom | external atom (read-only) | ReducedMotion ("no-preference" \| "reduce") | | prefersReducedMotionSelector | selector | boolean | | ReducedMotion | type | "no-preference" \| "reduce" |

Ownership

The preference belongs to the operating system — it is exposed as the OS "reduce motion" setting — so reducedMotionAtom is an external atom: it is read-only. Stores cannot write it, and set, reset and update reject it at compile time and at runtime.

Anything derived from it that the user can override — a per-app toggle, a remembered choice — is application state. Keep it in your own atom and resolve the effective value in your own selector:

import { atom, selector } from "valdres"
import { reducedMotionAtom, type ReducedMotion } from "@valdres/browser-reduced-motion"

type Preference = ReducedMotion | "system"

export const motionPreferenceAtom = atom<Preference>("system", {
    name: "app/motionPreference",
})

export const effectiveMotionSelector = selector<ReducedMotion>(
    get => {
        const preference = get(motionPreferenceAtom)
        return preference === "system" ? get(reducedMotionAtom) : preference
    },
    { name: "app/effectiveMotion" },
)

A picker sets motionPreferenceAtom, never the resolved value. Persisting the choice and applying it to the DOM are application concerns; this package stores nothing and touches no DOM.

Server rendering

reducedMotionAtom reports "no-preference" when the query cannot be observed — while server rendering, and in DOM-less or matchMedia-less runtimes. The value is a fixed, deterministic seed: a server cannot know a particular visitor's setting, and a mutable process-wide seed would leak between requests. useValue renders the seed first and swaps to the live value after hydration, which is a normal two-pass render rather than a hydration mismatch.

Lifetime and framework notes

The state is plain Valdres: an external atom plus a derived selector, readable from any store with store.get / store.sub. Adapter availability for this beta is listed under Usage — React today, the others once they migrate to the v1 core.

The media-query listener starts when a store tree first retains the source — through a direct subscription or a selector that reads it — and stops when that tree's last retaining subscriber leaves or the store is disposed. Each store tree owns its own listener; child scopes share their root's. Reads without a subscription report the current value without attaching anything.

Full documentation: https://valdres.dev/react/plugins/browser-reduced-motion