Naturally Produced Modules


    1.0.6 • Public • Published


    Detects user’s preferences for contrast using the prefers-contrast CSS3 level 5 media query.

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

    Magica11y cover


    Quoting from the CSS3 level 5 media queries specfication…

    The 'prefers-contrast' media feature is used to detect if the user has requested the system increase or decrease the amount of contrast between adjacent colors. For example, many users have difficulty reading text that has a small difference in contrast to the text background and would prefer a larger contrast.

    🔆 prefersContrast() 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. prefersContrast() 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 prefersContrast(), Magica11y also provides…

    🚀 Getting started

    🏗️ Installation

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

    $ yarn add "@magica11y/prefers-contrast"
    # OR
    $ npm install --save "@magica11y/prefers-contrast"

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

    <script src=""></script>
    <!-- OR -->
    <script src=""></script>

    🎲 Usage

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

    var contrastPreference = window.magica11y.prefersContrast.default();
    var useHighContrastColorScheme = (contrastPreference === window.magica11y.prefersContrast.contrastPreferences.HIGH);

    … or as a CommonJS module…

    const prefersContrast = require('@magica11y/prefers-contrast');
    const contrastPreference = prefersContrast.default();
    const useHighContrastColorScheme = (contrastPreference === prefersContrast.contrastPreferences.HIGH);

    … or as an ES module…

    import prefersContrast, { contrastPreferences } from '@magica11y/prefersContrast';
    const contrastPreference = prefersContrast();
    const useHighContrastColorScheme = (contrastPreference === contrastPreferences.HIGH);

    The contrastPreferences object contains all the possible values supported by the 'prefers-contrast' media query…

    • contrastPreferences.NO_PREFERENCE (spec: 'no-preference')

      Indicates that the user has made no preference known to the system.

    • contrastPreferences.HIGH (spec: 'high')

      Indicates that user has notified the system that they prefer an interface that has a higher level of contrast.

    • contrastPreferences.LOW (spec: 'low')

      Indicates that user has notified the system that they prefer an interface that has a lower level of contrast.

    • null

      The user’s preference could not be determined.

    🏁 Typechecking

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


    Now, you can use the Flow types as follows…

    // @flow
    import prefersContrast, { type ContrastPreference } from '@magica11y/prefers-contrast';
    const contrastPreference: ?ContrastPreference = prefersContrast();

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

    📜 License


    See for more details.

    Handcrafted with ❤️ by Rishabh.



    npm i @magica11y/prefers-contrast

    DownloadsWeekly Downloads






    Unpacked Size

    26.2 kB

    Total Files


    Last publish


    • rishabhsrao