@magica11y/light-level

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

Usage no npm install needed!

<script type="module">
  import magica11yLightLevel from 'https://cdn.skypack.dev/@magica11y/light-level';
</script>

README

: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.

Travis NPM Bundlephobia Bundlephobia Coveralls David DM David DM NodeJS License Snyk

Magica11y cover

: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 Bundlephobia minified, or Bundlephobia 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…

: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).

:scroll: License

License

See LICENSE.md for more details.

Handcrafted with :heart: by Rishabh.

Twitter