or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

browser-global.md browser-polyfill.md index.md postcss-plugin.md

tile.json

Browser Polyfill

The browser polyfill provides runtime JavaScript functionality that manages color scheme activation and enables programmatic control over theme switching. It works in conjunction with CSS transformed by the PostCSS plugin to provide complete prefers-color-scheme support across all browsers.

Capabilities

Initialization Function

Creates and initializes a color scheme manager that handles theme detection and switching.

/**
 * Initialize browser polyfill for prefers-color-scheme support
 * @param initialColorScheme - Optional initial color scheme preference
 * @param options - Optional configuration object
 * @returns ColorSchemeManager instance for managing color schemes
 */
declare function prefersColorSchemeInit(
  initialColorScheme?: 'dark' | 'light',
  options?: PolyfillOptions
): ColorSchemeManager;

Polyfill Options

Configuration options for the browser polyfill.

/**
 * Configuration options for the browser polyfill
 */
interface PolyfillOptions {
  /** 
   * Enable debug logging to console
   * @default false
   */
  debug?: boolean;
}

Color Scheme Manager

The object returned by prefersColorSchemeInit provides complete control over color scheme management.

/**
 * Manager object for controlling color scheme behavior
 */
interface ColorSchemeManager {
  /** 
   * Current color scheme getter/setter
   * Setting this property triggers immediate color scheme change
   */
  scheme: 'dark' | 'light';
  
  /** 
   * Whether the browser natively supports prefers-color-scheme media queries
   * @readonly
   */
  hasNativeSupport: boolean;
  
  /** 
   * Optional callback function called when color scheme changes
   * Triggered by both manual changes and system preference changes
   */
  onChange?: () => void;
  
  /** 
   * Remove system color scheme change listener
   * Call this when the polyfill is no longer needed to prevent memory leaks
   */
  removeListener(): void;
}

Usage Examples:

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

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

// Initialize with explicit scheme
const colorScheme = prefersColorSchemeInit('dark');

// Initialize with options
const colorScheme = prefersColorSchemeInit('light', { debug: true });

// Get current scheme
console.log(colorScheme.scheme); // 'dark' or 'light'

// Set scheme manually
colorScheme.scheme = 'dark';

// Check for native support
if (colorScheme.hasNativeSupport) {
  console.log('Browser supports prefers-color-scheme natively');
}

// Listen for changes
colorScheme.onChange = () => {
  console.log('Color scheme changed to:', colorScheme.scheme);
};

// Clean up when done
colorScheme.removeListener();

System Integration

The polyfill automatically integrates with the operating system's color scheme preference when available.

System Detection:

// The polyfill automatically detects system preference
const colorScheme = prefersColorSchemeInit();

// System changes are automatically reflected
// (requires browser support for matchMedia)

Manual Override:

// Override system preference
const colorScheme = prefersColorSchemeInit();
colorScheme.scheme = 'dark'; // Force dark mode regardless of system

CSS Integration

The polyfill works by manipulating the transformed CSS rules created by the PostCSS plugin.

How it works:

Searches all stylesheets for color media queries with special values
Activates matching queries by changing (color: X) to (max-color: X)
Deactivates non-matching queries by changing (max-color: X) to (color: X)
Removes any remaining native prefers-color-scheme queries to prevent conflicts

Color Values:

Dark scheme: (color: 48842621) → (max-color: 48842621) when active
Light scheme: (color: 70318723) → (max-color: 70318723) when active

Browser Compatibility

Supported Browsers:

Internet Explorer 9+
Safari 6+
Chrome (all versions)
Firefox (all versions)
Edge (all versions)

Feature Detection:

const colorScheme = prefersColorSchemeInit();

if (colorScheme.hasNativeSupport) {
  // Browser supports prefers-color-scheme natively
  // Polyfill will still work but may defer to native behavior
} else {
  // Browser needs polyfill for full functionality
}

Change Detection

The polyfill can detect and respond to system color scheme changes when the browser supports matchMedia.

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

const colorScheme = prefersColorSchemeInit();

// Set up change listener
colorScheme.onChange = () => {
  // Called when:
  // 1. System color scheme changes (if supported)
  // 2. Manual scheme change via colorScheme.scheme = 'dark'
  
  console.log('New color scheme:', colorScheme.scheme);
  
  // Update UI, save preference, etc.
  document.body.className = `theme-${colorScheme.scheme}`;
  localStorage.setItem('colorScheme', colorScheme.scheme);
};

CommonJS Usage

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

const colorScheme = prefersColorSchemeInit();
colorScheme.scheme = 'dark';

Error Handling

The polyfill includes error handling for CSS manipulation operations:

// With debug enabled, errors are logged to console
const colorScheme = prefersColorSchemeInit('dark', { debug: true });

// Without debug, errors are silently caught to prevent crashes
const colorScheme = prefersColorSchemeInit(); // debug: false (default)

Version

Tile

Files