Notify President Madagascar

    @magica11y/light-level

    1.0.7 • Public • Published

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

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

    Magica11y cover

    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, 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…

    🚀 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();

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

    📜 License

    License

    See LICENSE.md for more details.

    Handcrafted with ❤️ by Rishabh.

    Twitter

    Install

    npm i @magica11y/light-level

    DownloadsWeekly Downloads

    5

    Version

    1.0.7

    License

    MIT

    Unpacked Size

    25.7 kB

    Total Files

    14

    Last publish

    Collaborators

    • rishabhsrao