prefersContrast()

Detects user’s preferences for contrast using the prefers-contrast CSS3 level 5 media query.

:sparkles: Introduction

Quoting from the CSS3 level 5 media queries specfication…

The 'prefers-contrast' media feature is used to detect if the user has requested the system increase or decrease the amount of contrast between adjacent colors. For example, many users have difficulty reading text that has a small difference in contrast to the text background and would prefer a larger contrast.

:high_brightness: prefersContrast() is part of :crystal_ball: 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. prefersContrast() is just minified, or 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 prefersContrast(), Magica11y also provides…

• :tv: environmentBlending()
• :art: forcedColors()
• :new_moon: invertedColors()
• ~:candle: lightLevel()~
• :last_quarter_moon: prefersColorScheme()
• :roller_coaster: prefersReducedMotion()
• :gem: prefersReducedTransparency()

:rocket: Getting started

:building_construction: Installation

You can install prefersContrast() using a package manager such as yarn or npm…

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

You can also include prefersContrast() from a CDN on your page, such as jsDelivr or unpkg…

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

:game_die: Usage

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

var contrastPreference = window.magica11y.prefersContrast.default();
var useHighContrastColorScheme = (contrastPreference === window.magica11y.prefersContrast.contrastPreferences.HIGH);

… or as a CommonJS module…

const prefersContrast = require('@magica11y/prefers-contrast');
const contrastPreference = prefersContrast.default();
const useHighContrastColorScheme = (contrastPreference === prefersContrast.contrastPreferences.HIGH);

… or as an ES module…

import prefersContrast, { contrastPreferences } from '@magica11y/prefersContrast';

const contrastPreference = prefersContrast();
const useHighContrastColorScheme = (contrastPreference === contrastPreferences.HIGH);

The contrastPreferences object contains all the possible values supported by the 'prefers-contrast' media query…

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

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

• contrastPreferences.HIGH (spec: 'high')

  Indicates that user has notified the system that they prefer an interface that has a higher level of contrast.

• contrastPreferences.LOW (spec: 'low')

  Indicates that user has notified the system that they prefer an interface that has a lower level of contrast.

• null

  The user’s preference could not be determined.

:checkered_flag: Typechecking

You can import the Flow types from the provided libdefs in node_modules/@magica11y/prefers-contrast/lib by configuring them in your .flowconfig…

[libs]
node_modules/@magica11y/prefers-contrast/lib

Now, you can use the Flow types as follows…

// @flow
import prefersContrast, { type ContrastPreference } from '@magica11y/prefers-contrast';

const contrastPreference: ?ContrastPreference = prefersContrast();

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

:scroll: License

See LICENSE.md for more details.

Handcrafted with :heart: by Rishabh.