prefersColorScheme()

Detects user’s color scheme preferences using the prefers-color-scheme CSS3 level 5 media query.

@magica11y/prefers-color-scheme"">
@magica11y/prefers-color-scheme"">
@magica11y/prefers-color-scheme"">



@magica11y/prefers-color-scheme"">

Introduction

Quoting from the CSS3 level 5
media queries specfication…

The 'prefers-color-scheme' media feature reflects the user’s desire that the page use a light or dark color theme.

prefersColorScheme() 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. prefersColorScheme() is just @magica11y/prefers-color-scheme""> minified, or @magica11y/prefers-color-scheme""> 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 prefersColorScheme(), Magica11y also provides…

• environmentBlending()
• forcedColors()
• invertedColors()
• ~ lightLevel()~
• prefersContrast()
• prefersReducedMotion()
• prefersReducedTransparency()

Getting started

Installation

You can install prefersColorScheme() using a package manager such as @magica11y/prefers-color-scheme">yarn or @magica11y/prefers-color-scheme">npm…

$ yarn add "@magica11y/prefers-color-scheme"
# OR
$ npm install --save "@magica11y/prefers-color-scheme"

You can also include prefersColorScheme() from a CDN on your page, such as @magica11y/prefers-color-scheme">jsDelivr or @magica11y/prefers-color-scheme">unpkg…

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

Usage

prefersColorScheme() is distributed as a UMD module, so you can use it as a browser global…

var preferredColorScheme = window.magica11y.prefersColorScheme.default();
var enableDarkTheme = (preferredColorScheme === window.magica11y.prefersColorScheme.colorSchemes.DARK);

… or as a CommonJS module…

const prefersColorScheme = require('@magica11y/prefers-color-scheme');
const preferredColorScheme = prefersColorScheme.default();
const enableDarkTheme = (preferredColorScheme === prefersColorScheme.colorSchemes.DARK);

… or as an ES module…

import prefersColorScheme, { colorSchemes } from '@magica11y/prefersColorScheme';
const preferredColorScheme = prefersColorScheme();
const enableDarkTheme = (preferredColorScheme === colorSchemes.DARK);

The colorSchemes object contains all the possible values supported by the 'prefers-color-scheme' media query…

• colorSchemes.LIGHT (spec: 'light')

  Indicates that user has expressed the preference for a page that has a light theme (dark text on light background), or has not expressed an active preference (and thus should receive the “web default” of a light theme).

• colorSchemes.DARK (spec: 'dark')

  Indicates that user has expressed the preference for a page that has a dark theme (light text on dark background).

• 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-color-scheme/lib by configuring them in your .flowconfig…

[libs]
node_modules/@magica11y/prefers-color-scheme/lib

Now, you can use the Flow types as follows…

// @flow
import prefersColorScheme, { type ColorScheme } from '@magica11y/prefers-color-scheme';
const preferredColorScheme: ?ColorScheme = prefersColorScheme();

Note: prefersColorScheme() returns a nullable
type (i.e. ColorScheme). So using the ? prefix to indicate nullable types is recommended (i.e. ?ColorScheme).

License

See LICENSE.md for more details.

Handcrafted with  by Rishabh.