Needful Program Management


    2.0.3 • Public • Published


    Detects user’s color scheme preferences using the prefers-color-scheme 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-color-scheme' media feature reflects the user’s desire that the page use a light or dark color theme.

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

    🚀 Getting started

    🏗️ Installation

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

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

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

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

    🎲 Usage

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

    var preferredColorScheme = window.magica11y.prefersColorScheme.default();
    var enableDarkTheme = (preferredColorScheme === window.magica11y.prefersColorScheme.colorSchemes.DARK);

    … or as a CommonJS module…

    const prefersColorScheme = require('@magica11y/prefers-color-scheme');
    const preferredColorScheme = prefersColorScheme.default();
    const enableDarkTheme = (preferredColorScheme === prefersColorScheme.colorSchemes.DARK);

    … or as an ES module…

    import prefersColorScheme, { colorSchemes } from '@magica11y/prefersColorScheme';
    const preferredColorScheme = prefersColorScheme();
    const enableDarkTheme = (preferredColorScheme === colorSchemes.DARK);

    The colorSchemes object contains all the possible values supported by the 'prefers-color-scheme' media query…

    • colorSchemes.LIGHT (spec: 'light')

      Indicates that user has expressed the preference for a page that has a light theme (dark text on light background), or has not expressed an active preference (and thus should receive the "web default" of a light theme).

    • colorSchemes.DARK (spec: 'dark')

      Indicates that user has expressed the preference for a page that has a dark theme (light text on dark background).

    • 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-color-scheme/lib by configuring them in your .flowconfig


    Now, you can use the Flow types as follows…

    // @flow
    import prefersColorScheme, { type ColorScheme } from '@magica11y/prefers-color-scheme';
    const preferredColorScheme: ?ColorScheme = prefersColorScheme();

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

    📜 License


    See for more details.

    Handcrafted with ❤️ by Rishabh.



    npm i @magica11y/prefers-color-scheme

    DownloadsWeekly Downloads






    Unpacked Size

    25.8 kB

    Total Files


    Last publish


    • rishabhsrao