@magica11y/light-level NPM

:skull: Deprecation notice

The light-level media query was deprecated in the 2020-07-15 draft because it is redundant with the prefers-contrast and prefers-color-scheme.

Please use the other Magica11y functions, :last_quarter_moon: prefersColorScheme() and :high_brightness: prefersContrast(), instead.

`lightLevel()`

Detects the ambient light-level of the user’s device using the light-level CSS3 level 5 media query.

:sparkles: Introduction

Quoting from the CSS3 level 5 media queries specfication…

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

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

:tv: environmentBlending()
:new_moon: invertedColors()
:art: forcedColors()
:last_quarter_moon: prefersColorScheme()
:high_brightness: prefersContrast()
:roller_coaster: prefersReducedMotion()
:gem: prefersReducedTransparency()

:rocket: Getting started

:building_construction: Installation

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

$ yarn add "@magica11y/light-level"
# OR
$ npm install --save "@magica11y/light-level"

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

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

:game_die: Usage

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

var currentLightLevel = window.magica11y.lightLevel.default();
var disableAnimations = (currentLightLevel === window.magica11y.lightLevel.availableLightLevels.DIM);

… or as a CommonJS module…

const lightLevel = require('@magica11y/light-level');
const currentLightLevel = lightLevel.default();
const disableAnimations = (currentLightLevel === lightLevel.availableLightLevels.DIM);

… or as an ES module…

import lightLevel, { availableLightLevels } from '@magica11y/lightLevel';

const currentLightLevel = lightLevel();
const enableDarkMode = (currentLightLevel === availableLightLevels.DIM);

The availableLightLevels object contains all the possible values supported by the 'light-level' media query…

availableLightLevels.NORMAL (spec: 'normal')
The device is used in a environment with a light level in the ideal range for the screen, and which does not necessitate any particular adjustment.
availableLightLevels.DIM (spec: 'dim')
The device is used in a dim environment, where excessive contrast and brightness would be distracting or uncomfortable to the reader. For example: night time, or a dimly illuminated indoor environment.
availableLightLevels.WASHED (spec: 'washed')
The device is used in an exceptionally bright environment, causing the screen to be washed out and difficult to read. For example: bright daylight.
null
The device’s ambient light-level could not be determined.

:checkered_flag: Typechecking

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

[libs]
node_modules/@magica11y/light-level/lib

Now, you can use the Flow types as follows…

// @flow
import lightLevel, { type LightLevel } from '@magica11y/light-level';

const currentLightLevel: ?LightLevel = lightLevel();

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