Skip to content

šŸŽ¢ Detects userā€™s preferences for reduced motion using the 'prefers-reduce-motion' CSS3 level 5 media query.

License

Notifications You must be signed in to change notification settings

magica11y/prefers-reduced-motion

Repository files navigation

prefersReducedMotion()

Detects userā€™s preferences for reduced motion using the prefers-reduce-motion CSS3 level 5 media query.

Travis NPM Bundlephobia Bundlephobia Coveralls David DM David DM NodeJS License Snyk

Magica11y cover

āœØ Introduction

Quoting from the CSS3 level 5 media queries specficationā€¦

The prefers-reduced-motion media feature is used to detect if the user has requested the system to minimize the amount of animation or motion it uses.

šŸŽ¢ prefersReducedMotion() is part of šŸ”® Magica11y, which provides a suite of functions to detect ā€œuser-preferenceā€ and ā€œenvironmentā€ media features.

Magica11y functions are awesome becauseā€¦

  • They have zero dependencies
  • Theyā€™re lightweight; e.g. prefersReducedMotion() is just Bundlephobia minified, or Bundlephobia minified & gzippā€™d
  • They use the window.matchMedia API underneath
  • Theyā€™re optimized for performance; all the module functions are designed in such a way that they exit early
  • They provide a clean, well-documented and semantic API to work with

In addition to prefersReducedMotion(), Magica11y also providesā€¦

šŸš€ Getting started

šŸ—ļø Installation

You can install prefersReducedMotion() using a package manager such as yarn or npmā€¦

$ yarn add "@magica11y/prefers-reduced-motion"
# OR
$ npm install --save "@magica11y/prefers-reduced-motion"

You can also include prefersReducedMotion() from a CDN on your page, such as jsDelivr or unpkgā€¦

<script src="https://cdn.jsdelivr.net/npm/@magica11y/prefers-reduced-motion@latest/dist/magica11y.prefersReducedMotion.min.js"></script>
<!-- OR -->
<script src="https://unpkg.com/@magica11y/prefers-reduced-motion@latest/dist/magica11y.prefersReducedMotion.js"></script>

šŸŽ² Usage

prefersReducedMotion() is distributed as a UMD module, so you can use it as a browser globalā€¦

var motionPreference = window.magica11y.prefersReducedMotion.default();
var disableAnimations = (motionPreference === window.magica11y.prefersReducedMotion.motionPreferences.REDUCE);

ā€¦ or as a CommonJS moduleā€¦

const prefersReducedMotion = require('@magica11y/prefers-reduced-motion');
const motionPreference = prefersReducedMotion.default();
const disableAnimations = (motionPreference === prefersReducedMotion.motionPreferences.REDUCE);

ā€¦ or as an ES moduleā€¦

import prefersReducedMotion, { motionPreferences } from '@magica11y/prefers-reduced-motion';

const motionPreference = prefersReducedMotion();
const disableAnimations = (motionPreference === motionPreferences.REDUCE);

The motionPreferences object contains all the possible values supported by the 'prefers-reduce-motion' media queryā€¦

  • motionPreferences.NO_PREFERENCE (spec: 'no-preference')

    Indicates that the user has made no preference known to the system.

  • motionPreferences.REDUCE (spec: 'reduce')

    Indicates that user has notified the system that they prefer an interface that minimizes the amount of movement or animation, preferably to the point where all non-essential movement is removed.

  • null

    The userā€™s preference could not be determined.

šŸ Typechecking

You can import the Flow types from the provided libdefs in node_modules/@magica11y/prefers-reduced-motion/lib by configuring them in your .flowconfigā€¦

[libs]
node_modules/@magica11y/prefers-reduced-motion/lib

Now, you can use the Flow types as followsā€¦

// @flow
import prefersReducedMotion, { type MotionPreference } from '@magica11y/prefers-reduced-motion';

const motionPreference: ?MotionPreference = prefersReducedMotion();

šŸŽ© Note: prefersReducedMotion() returns a nullable type (i.e. MotionPreference). So using the ? prefix to indicate nullable types is recommended (i.e. ?MotionPreference).

šŸ“š Further reading

šŸ“œ License

License

See LICENSE.md for more details.

Handcrafted withā€ƒ:heart:ā€ƒby Rishabh.

Twitter

About

šŸŽ¢ Detects userā€™s preferences for reduced motion using the 'prefers-reduce-motion' CSS3 level 5 media query.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published