or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdevent-system.mdindex.mdinternal-apis.mdreact-integration.md
tile.json

tessl/npm-storybook-dark-mode

Toggle between light and dark mode in Storybook

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/storybook-dark-mode@3.0.x

To install, run

npx @tessl/cli install tessl/npm-storybook-dark-mode@3.0.0

index.mddocs/

Storybook Dark Mode

Storybook Dark Mode is a Storybook addon that enables users to toggle between light and dark mode themes within the Storybook interface. It provides comprehensive theme customization through configuration parameters, React hooks for component integration, and programmatic theme control with localStorage persistence.

Package Information

  • Package Name: storybook-dark-mode
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev storybook-dark-mode

Core Imports

import { useDarkMode } from 'storybook-dark-mode';

For event-based integration:

import { 
  DARK_MODE_EVENT_NAME, 
  UPDATE_DARK_MODE_EVENT_NAME 
} from 'storybook-dark-mode';

For advanced/internal APIs:

import { store, updateStore, prefersDark } from 'storybook-dark-mode';

Basic Usage

1. Add to Storybook Configuration

Add to .storybook/main.js:

module.exports = {
  addons: ['storybook-dark-mode']
};

2. Configure Themes (Optional)

Configure themes in .storybook/preview.js:

import { themes } from '@storybook/theming';

export const parameters = {
  darkMode: {
    // Override the default dark theme
    dark: { ...themes.dark, appBg: 'black' },
    // Override the default light theme
    light: { ...themes.normal, appBg: 'red' },
    // Set the initial theme
    current: 'light'
  }
};

3. React Integration

Use the hook to integrate with your components:

import React from 'react';
import { useDarkMode } from 'storybook-dark-mode';

function ThemeWrapper({ children }) {
  const isDark = useDarkMode();
  
  return (
    <div className={isDark ? 'dark-theme' : 'light-theme'}>
      {children}
    </div>
  );
}

Architecture

Storybook Dark Mode is built around several key components:

  • Addon Integration: Automatic registration with Storybook's addon system via preset configuration
  • Theme Management: Centralized theme storage and persistence using localStorage
  • Event System: Channel-based communication for theme state synchronization across Storybook
  • React Integration: Hook-based API for component-level theme awareness
  • CSS Class Management: Automatic application of theme classes to manager and preview iframes
  • OS Preference Detection: Automatic theme detection based on user's system preferences

Capabilities

React Hook Integration

React hook for accessing current theme state within Storybook stories and components.

function useDarkMode(): boolean;

React Integration

Configuration System

Comprehensive configuration options for customizing themes, CSS classes, and behavior through Storybook parameters.

type DarkModeParameters = Partial<DarkModeStore>;

Configuration

Event-Based Theme Control

Event system for manual theme control and integration with custom components.

const DARK_MODE_EVENT_NAME: 'DARK_MODE';
const UPDATE_DARK_MODE_EVENT_NAME: 'UPDATE_DARK_MODE';

Event System

Internal APIs

Advanced APIs for low-level theme management, store functions, and OS preference detection.

function store(userTheme?: Partial<DarkModeStore>): DarkModeStore;
function updateStore(newStore: DarkModeStore): void;
const prefersDark: MediaQueryList;

Internal APIs

Types

type Mode = 'light' | 'dark';

interface DarkModeStore {
  /** CSS selector for preview iframe target element */
  classTarget: string;
  /** Current active theme mode */
  current: Mode;
  /** Dark theme configuration object */
  dark: ThemeVars;
  /** CSS class(es) applied in dark mode */
  darkClass: string | string[];
  /** Light theme configuration object */
  light: ThemeVars;
  /** CSS class(es) applied in light mode */
  lightClass: string | string[];
  /** Whether to apply theme classes to preview iframe */
  stylePreview: boolean;
  /** Whether user has manually set a theme preference */
  userHasExplicitlySetTheTheme: boolean;
}

/**
 * Storybook theme configuration object (from @storybook/theming)
 * Used to customize the appearance of the Storybook UI
 */
interface ThemeVars {
  /** Main application background color */
  appBg?: string;
  /** Content area background color */
  appContentBg?: string;
  /** Border color for UI elements */
  appBorderColor?: string;
  /** Border radius for UI elements */
  appBorderRadius?: number;
  /** Base font family */
  fontBase?: string;
  /** Code/monospace font family */
  fontCode?: string;
  /** Primary text color */
  textColor?: string;
  /** Toolbar text color */
  barTextColor?: string;
  /** Selected toolbar item color */
  barSelectedColor?: string;
  /** Toolbar background color */
  barBg?: string;
  /** Input field background color */
  inputBg?: string;
  /** Input field border color */
  inputBorder?: string;
  /** Input field text color */
  inputTextColor?: string;
  /** Input field border radius */
  inputBorderRadius?: number;
  /** Brand title text */
  brandTitle?: string;
  /** Brand URL for logo/title links */
  brandUrl?: string;
  /** Brand image/logo URL */
  brandImage?: string;
  /** Brand target attribute for links */
  brandTarget?: string;
  /** Color palette */
  colorPrimary?: string;
  colorSecondary?: string;
  /** Additional theme properties as defined by Storybook theming */
  [key: string]: any;
}