Storybook Addon Themes

Storybook Addon Themes enables theme switching functionality within the Storybook preview environment. It provides multiple decorators for different theming strategies including CSS classes, data attributes, and JSX providers, making it compatible with popular styling solutions like styled-components, emotion, Material-UI, Tailwind CSS, and Bootstrap.

Package Information

• Package Name: @storybook/addon-themes
• Package Type: npm
• Language: TypeScript
• Installation: npm install -D @storybook/addon-themes
• Storybook Version: 7.0 or later
• Peer Dependencies: storybook (workspace:^)

Core Imports

import { 
  withThemeByClassName, 
  withThemeByDataAttribute, 
  withThemeFromJSXProvider,
  DecoratorHelpers,
  type ThemesTypes
} from "@storybook/addon-themes";

// Default export for addon registration
import addonThemes from "@storybook/addon-themes";

For CommonJS:

const { 
  withThemeByClassName, 
  withThemeByDataAttribute, 
  withThemeFromJSXProvider,
  DecoratorHelpers
} = require("@storybook/addon-themes");

// Default export
const addonThemes = require("@storybook/addon-themes").default;

Basic Usage

Add the addon to your Storybook configuration:

// .storybook/main.js
export default {
  addons: ['@storybook/addon-themes'],
};

Configure theme switching in your preview:

// .storybook/preview.js
import { withThemeByClassName } from '@storybook/addon-themes';

export const decorators = [
  withThemeByClassName({
    themes: {
      light: 'light-theme',
      dark: 'dark-theme',
    },
    defaultTheme: 'light',
  }),
];

Architecture

The addon is built around several key components:

• Theme Decorators: Three main decorators for different theming approaches (CSS classes, data attributes, JSX providers)
• Helper Functions: Utilities for accessing theme state and creating custom decorators
• Manager Integration: UI components for theme switching in the Storybook toolbar
• Global State Management: Theme state synchronization between manager and preview
• Event System: Communication channel for theme registration and updates

Capabilities

CSS Class-Based Theming

Theme switching by applying CSS classes to parent elements. Ideal for CSS frameworks and traditional stylesheet-based themes.

function withThemeByClassName<TRenderer extends Renderer = Renderer>(
  config: ClassNameStrategyConfiguration
): DecoratorFunction<TRenderer>;

interface ClassNameStrategyConfiguration {
  themes: Record<string, string>;
  defaultTheme: string;
  parentSelector?: string;
}

CSS Class Theming

Data Attribute-Based Theming

Theme switching by setting data attributes on parent elements. Perfect for CSS custom properties and attribute-based selectors.

function withThemeByDataAttribute<TRenderer extends Renderer = any>(
  config: DataAttributeStrategyConfiguration
): DecoratorFunction<TRenderer>;

interface DataAttributeStrategyConfiguration {
  themes: Record<string, string>;
  defaultTheme: string;
  parentSelector?: string;
  attributeName?: string;
}

Data Attribute Theming

JSX Provider-Based Theming

Theme switching using JSX provider components and theme objects. Designed for component libraries like styled-components, emotion, and Material-UI.

function withThemeFromJSXProvider<TRenderer extends Renderer = any>(
  config: ProviderStrategyConfiguration
): DecoratorFunction<TRenderer>;

interface ProviderStrategyConfiguration {
  Provider?: any;
  GlobalStyles?: any;
  defaultTheme?: string;
  themes?: Record<string, any>;
}

JSX Provider Theming

Custom Decorator Helpers

Utilities for building custom theme decorators when the built-in decorators don't meet specific requirements.

namespace DecoratorHelpers {
  function pluckThemeFromContext(context: StoryContext): string;
  function initializeThemeState(themeNames: string[], defaultTheme: string): void;
  function useThemeParameters(context?: StoryContext): ThemesParameters;
}

Custom Decorators

Default Export

The package's default export is a function that creates a Storybook addon definition for use with Storybook's internal addon system.

/**
 * Creates a Storybook addon definition with theme support
 * @returns Storybook addon definition
 */
function default(): PreviewAddon<ThemesTypes>;

This export is automatically used by Storybook when the addon is registered in your .storybook/main.js addons array. You typically don't need to import or use this directly unless you're building custom addon integrations.

Types

interface ThemesTypes {
  parameters: ThemesParameters;
  globals: ThemesGlobals;
}

interface ThemesParameters {
  themes?: {
    disable?: boolean;
    themeOverride?: string;
  };
}

interface ThemesGlobals {
  theme?: string;
}

interface ThemeAddonState {
  themesList: string[];
  themeDefault?: string;
}

Internal Constants

The addon exports several internal constants used for its operation. These are not part of the public API and should not be used directly in consuming code:

• PARAM_KEY - Parameter key for theme configuration
• GLOBAL_KEY - Global key for theme state
• ADDON_ID - Unique addon identifier
• THEME_SWITCHER_ID - Theme switcher component identifier
• THEMING_EVENTS - Event constants for theme communication

These constants are implementation details and may change between releases.