CSS Prefers Color Scheme

CSS Prefers Color Scheme is a comprehensive PostCSS plugin and browser polyfill that enables the use of prefers-color-scheme media queries across all browsers, including legacy versions that don't natively support this CSS Media Queries Level 5 feature.

Package Information

• Package Name: css-prefers-color-scheme
• Package Type: npm
• Language: TypeScript
• Version: 10.0.0
• License: MIT-0
• Installation: npm install css-prefers-color-scheme --save-dev

Core Imports

For PostCSS plugin usage:

// ES Modules
import prefersColorScheme from 'css-prefers-color-scheme';

// CommonJS
const prefersColorScheme = require('css-prefers-color-scheme');

For browser polyfill:

// ES Modules
import prefersColorSchemeInit from 'css-prefers-color-scheme/browser';

// CommonJS
const prefersColorSchemeInit = require('css-prefers-color-scheme/browser');

For browser global (CDN):

<script src="https://unpkg.com/css-prefers-color-scheme@10.0.0/dist/browser-global.js"></script>

Basic Usage

PostCSS Plugin:

const postcss = require('postcss');
const prefersColorScheme = require('css-prefers-color-scheme');

postcss([
  prefersColorScheme(/* options */)
]).process(yourCSS, { from: undefined });

Browser Polyfill:

import prefersColorSchemeInit from 'css-prefers-color-scheme/browser';

// Auto-detect OS preference
const colorScheme = prefersColorSchemeInit();

// Manual control
colorScheme.scheme = 'dark';

Architecture

CSS Prefers Color Scheme operates through two complementary components:

• Build-time Transformation: PostCSS plugin transforms prefers-color-scheme media queries into cross-browser compatible color media queries during the build process
• Runtime Polyfill: Browser polyfill dynamically activates the appropriate color scheme based on user preference or system settings
• Cross-browser Compatibility: Works in browsers as old as Internet Explorer 9 through modern browsers with native support

How It Works

The plugin transforms CSS media queries using special color values:

• @media (prefers-color-scheme: dark) → @media (color: 48842621)
• @media (prefers-color-scheme: light) → @media (color: 70318723)

The browser polyfill then manipulates these color queries to activate the correct scheme, while automatically removing native prefers-color-scheme queries to prevent conflicts.

Capabilities

PostCSS Plugin

Build-time CSS transformation that converts prefers-color-scheme media queries into cross-browser compatible alternatives. Essential for supporting legacy browsers in production builds.

declare const prefersColorScheme: PluginCreator<pluginOptions>;

interface pluginOptions {
  /** Preserve the original notation. Default: true */
  preserve?: boolean;
}

PostCSS Plugin

Browser Polyfill

Runtime JavaScript polyfill that manages color scheme activation and provides programmatic control over theme switching. Works with transformed CSS to enable dynamic color scheme changes.

declare function prefersColorSchemeInit(
  initialColorScheme?: 'dark' | 'light',
  options?: { debug?: boolean }
): ColorSchemeManager;

interface ColorSchemeManager {
  /** Current color scheme getter/setter */
  scheme: 'dark' | 'light';
  /** Whether browser natively supports prefers-color-scheme */
  hasNativeSupport: boolean;
  /** Callback function called when color scheme changes */
  onChange?: () => void;
  /** Remove system color scheme change listener */
  removeListener(): void;
}

Browser Polyfill

Browser Global

Global script version of the browser polyfill for CDN usage and legacy integration patterns.

declare var prefersColorSchemeInit: typeof import('./browser-polyfill').prefersColorSchemeInit;

Browser Global