prefersReducedTransparency()

Detects user’s transparency preferences using the prefers-reduced-transparency CSS3 level 5 media query.

:sparkles: Introduction

Quoting from the CSS3 level 5 media queries specfication…

The 'prefers-reduced-transparency' media feature is used to detect if the user has requested the system minimize the amount of transparent or translucent layer effects it uses.

:high_brightness: prefersReducedTransparency() 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. prefersReducedTransparency() 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 prefersReducedTransparency(), Magica11y also provides…

• :tv: environmentBlending()
• :art: forcedColors()
• :new_moon: invertedColors()
• :candle: lightLevel()
• :high_brightness: prefersContrast()
• :roller_coaster: prefersReducedMotion()
• :last_quarter_moon: prefersColorScheme()

:rocket: Getting started

:building_construction: Installation

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

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

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

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

:game_die: Usage

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

var transparencyPreference = window.magica11y.prefersReducedTransparency.default();
var reduceTransparency = (transparencyPreference === window.magica11y.prefersReducedTransparency.transparencyPreferences.DARK);

… or as a CommonJS module…

const prefersReducedTransparency = require('@magica11y/prefers-reduced-transparency');
const transparencyPreference = prefersReducedTransparency.default();
const reduceTransparency = (transparencyPreference === prefersReducedTransparency.transparencyPreferences.REDUCE);

… or as an ES module…

import prefersReducedTransparency, { transparencyPreferences } from '@magica11y/prefersReducedTransparency';

const transparencyPreference = prefersReducedTransparency();
const reduceTransparency = (transparencyPreference === transparencyPreferences.REDUCE);

The transparencyPreferences object contains all the possible values supported by the 'prefers-reduced-transparency' media query…

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

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

• transparencyPreferences.REDUCE (spec: 'reduce')

  Indicates that user has notified the system that they prefer an interface that minimizes the amount of transparent or translucent layer effects.

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

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

Now, you can use the Flow types as follows…

// @flow
import prefersReducedTransparency, { type TransparencyPreference } from '@magica11y/prefers-reduced-transparency';

const transparencyPreference: ?TransparencyPreference = prefersReducedTransparency();

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

:scroll: License

See LICENSE.md for more details.

Handcrafted with :heart: by Rishabh.