💀 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, prefersColorScheme()
and prefersContrast()
, instead.
lightLevel()
Detects the ambient light-level of the user’s device using the
light-level
CSS3 level 5 media query.
✨ 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.
lightLevel()
is part of
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…
-
📺 environmentBlending()
-
🌑 invertedColors()
-
🎨 forcedColors()
-
🌗 prefersColorScheme()
-
🔆 prefersContrast()
-
🎢 prefersReducedMotion()
-
💎 prefersReducedTransparency()
🚀 Getting started
🏗️ 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>
🎲 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.
🏁 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();
lightLevel()
returns a nullable
type (i.e. LightLevel
). So using the ?
prefix to indicate nullable types is recommended (i.e. ?LightLevel
).
📜 License
See LICENSE.md for more details.
Handcrafted with