@magica11y/light-level
v1.0.7
Published
Detects the ambient light-level of the user’s device using the 'light-level' CSS3 level 5 media query.
Downloads
9
Maintainers
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.
: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
).
:scroll: License
See LICENSE.md for more details.
Handcrafted with :heart: by Rishabh.