https://github.com/magica11y/prefers-contrast
🔆 Detects user’s preferences for contrast using the 'prefers-contrast' CSS3 level 5 media query.
https://github.com/magica11y/prefers-contrast
a11y accessibility css-mediaquery matchmedia prefers-contrast
Last synced: 3 months ago
JSON representation
🔆 Detects user’s preferences for contrast using the 'prefers-contrast' CSS3 level 5 media query.
- Host: GitHub
- URL: https://github.com/magica11y/prefers-contrast
- Owner: magica11y
- License: mit
- Created: 2019-07-28T06:50:54.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2025-01-20T18:31:00.000Z (5 months ago)
- Last Synced: 2025-03-07T09:35:46.773Z (3 months ago)
- Topics: a11y, accessibility, css-mediaquery, matchmedia, prefers-contrast
- Language: JavaScript
- Homepage: https://magica11y.github.io
- Size: 941 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
`prefersContrast()`
==================
> Detects user’s preferences for contrast using the `prefers-contrast` CSS3 level 5 media query.
[](https://github.com/magica11y/prefers-contrast/actions/workflows/test.yml)
[](https://www.npmjs.com/package/@magica11y/prefers-contrast)
[](https://bundlephobia.com/result?p=@magica11y/prefers-contrast)
[](https://bundlephobia.com/result?p=@magica11y/prefers-contrast)
[](https://coveralls.io/github/magica11y/prefers-contrast)
[](https://www.npmjs.com/package/@magica11y/prefers-contrast)
[](LICENSE.md)
[](https://magica11y.github.io)
# :sparkles: Introduction
Quoting from the [CSS3](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS3) [level 5](https://www.w3.org/TR/mediaqueries-5)
[media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries) specfication…
> The [`'prefers-contrast'`](https://drafts.csswg.org/mediaqueries-5/#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**](https://magica11y.github.io),
which provides a suite of functions to detect “user-preference” and “environment” media features.
[Magica11y](https://magica11y.github.io) functions are awesome because…
* They have **zero** dependencies
* They’re **lightweight**; e.g. `prefersContrast()` is just [](https://bundlephobia.com/result?p=@magica11y/prefers-contrast) minified, or [](https://bundlephobia.com/result?p=@magica11y/prefers-contrast) minified & gzipp’d
* They use the **[`window.matchMedia`](https://developer.mozilla.org/docs/Web/API/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](https://magica11y.github.io) also provides…
* :tv: [`environmentBlending()`](https://github.com/magica11y/environment-blending)
* :art: [`forcedColors()`](https://github.com/magica11y/forced-colors)
* :new_moon: [`invertedColors()`](https://github.com/magica11y/inverted-colors)
* ~:candle: [`lightLevel()`](https://github.com/magica11y/light-level)~
* :last_quarter_moon: [`prefersColorScheme()`](https://github.com/magica11y/prefers-color-scheme)
* :roller_coaster: [`prefersReducedMotion()`](https://github.com/magica11y/prefers-reduced-motion)
* :gem: [`prefersReducedTransparency()`](https://github.com/magica11y/prefers-reduced-transparency)
# :rocket: Getting started
## :building_construction: Installation
You can install `prefersContrast()` using a package manager such as [`yarn`](https://yarnpkg.com/en/package/@magica11y/prefers-contrast) or [`npm`](https://www.npmjs.com/package/@magica11y/prefers-contrast)…
```sh
$ 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](https://www.jsdelivr.com/package/npm/@magica11y/prefers-contrast) or [unpkg](https://unpkg.com/@magica11y/prefers-contrast)…
```html
```
## :game_die: Usage
`prefersContrast()` is distributed as a [UMD](https://github.com/umdjs/umd) module, so you can use it as a browser global…
```js
var contrastPreference = window.magica11y.prefersContrast.default();
var useHighContrastColorScheme = (contrastPreference === window.magica11y.prefersContrast.contrastPreferences.MORE);
```
… or as a CommonJS module…
```js
const prefersContrast = require('@magica11y/prefers-contrast');
const contrastPreference = prefersContrast.default();
const useHighContrastColorScheme = (contrastPreference === prefersContrast.contrastPreferences.MORE);
```
… or as an ES module…
```js
import prefersContrast, { contrastPreferences } from '@magica11y/prefersContrast';
const contrastPreference = prefersContrast();
const useHighContrastColorScheme = (contrastPreference === contrastPreferences.MORE);
```
The `contrastPreferences` object contains all the possible values supported by the `'prefers-contrast'` media query…
* `contrastPreferences.NO_PREFERENCE` (spec: [`'no-preference'`](https://www.w3.org/TR/mediaqueries-5/#valdef-media-prefers-contrast-no-preference))
> Indicates that the user has made no preference known to the system.
* `contrastPreferences.HIGH` (spec: [`'high'`](https://www.w3.org/TR/mediaqueries-5/#valdef-media-prefers-contrast-high))
> Indicates that user has notified the system that they prefer an interface that has a higher level of contrast.
* `contrastPreferences.LOW` (spec: [`'low'`](https://www.w3.org/TR/mediaqueries-5/#valdef-media-prefers-contrast-low))
> Indicates that user has notified the system that they prefer an interface that has a lower level of contrast.
* `contrastPreferences.CUSTOM` (spec: [`'custom'`](https://www.w3.org/TR/mediaqueries-5/#valdef-media-prefers-contrast-custom))
> Indicates that the user has indicated wanting a specific set of colors to be used,
> but the contrast implied by these particular colors is such that neither `more` nor `less` match.
* `null`
> The user’s preference could not be determined.
# :checkered_flag: Typechecking
You can import the [Flow](https://flow.org) types from the provided [libdefs](https://flow.org/en/docs/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…
```js
// @flow
import prefersContrast, { type ContrastPreference } from '@magica11y/prefers-contrast';
const contrastPreference: ?ContrastPreference = prefersContrast();
```
:tophat: **Note**: `prefersContrast()` returns a [`nullable`](https://flow.org/en/docs/types/primitives/#toc-null-and-void)
type (i.e. `ContrastPreference`). So using the `?` prefix to indicate nullable types is recommended (i.e. `?ContrastPreference`).
# :scroll: License
[](LICENSE.md)
See [LICENSE.md](LICENSE.md) for more details.
Handcrafted with :hearts: by [Rishabh](https://rishabh.ink).
[](https://twitter.com/rishabh_ink)