Provider System

ChakraProvider integration that automatically wraps Storybook stories with Chakra UI theming support, direction control, and color mode synchronization. The provider system ensures stories render with proper Chakra UI context and responds to toolbar control changes.

Capabilities

Provider Decorator

Main decorator that wraps stories with ChakraBaseProvider and handles theme configuration, direction switching, and color mode synchronization.

/**
 * Storybook decorator that wraps stories with ChakraBaseProvider
 * Handles theme parameters, direction control, and color mode sync
 */
const Provider: DecoratorFunction<Renderer>;

The Provider decorator is automatically applied when using the addon. It processes the following:

• Theme Parameters: Applies theme from story/global parameters
• Direction Control: Responds to direction toolbar tool changes
• Color Mode Sync: Integrates ColorModeSync component

Usage Examples:

// The Provider is automatically applied by the addon
// Stories are automatically wrapped without manual configuration

// Global theme configuration in .storybook/preview.js
export const parameters = {
  chakra: {
    theme: myTheme,
    colorModeManager: "localStorage", // optional
  },
};

// Per-story theme override
export const CustomThemeStory = Template.bind({});
CustomThemeStory.parameters = {
  chakra: {
    theme: customTheme,
  },
};

Direction Hook

React hook for managing and synchronizing layout direction (LTR/RTL) with the HTML document and Storybook toolbar.

/**
 * Hook for managing layout direction with DOM synchronization
 * @param initialDirection - Initial direction, defaults to "ltr"
 * @returns Current direction string
 */
function useDirection(initialDirection: "ltr" | "rtl" = "ltr"): string;

Usage Examples:

import { useDirection } from "@chakra-ui/storybook-addon";

// In custom story decorator
const CustomDecorator = (Story, context) => {
  const direction = useDirection("ltr");
  
  return (
    <div dir={direction}>
      <Story />
    </div>
  );
};

// The hook automatically:
// - Sets document.documentElement.dir
// - Listens for TOGGLE_DIRECTION events
// - Updates direction state reactively

Color Mode Synchronization

Component that synchronizes Storybook's color mode control with Chakra UI's color mode system.

/**
 * Component that syncs Storybook color mode with Chakra UI
 * Renders null but maintains event listeners for color mode changes
 */
function ColorModeSync(): null;

The ColorModeSync component:

• Listens for TOGGLE_COLOR_MODE events from the toolbar
• Uses Chakra UI's useColorMode hook to update theme
• Maintains synchronization between Storybook and Chakra UI states

Integration Example:

// Automatically included in Provider decorator
<ChakraBaseProvider theme={themeWithDirectionOverride}>
  <ColorModeSync />
  <>{getStory(context)}</>
</ChakraBaseProvider>

Provider Implementation Details

The Provider decorator uses Storybook's makeDecorator utility with the following configuration:

interface ProviderOptions {
  name: "ChakraProviderDecorator";
  parameterName: "chakra";
  skipIfNoParametersOrOptions: false;
}

Parameter Processing:

The decorator processes chakra parameters from story context:

• theme: Custom theme object to extend base theme
• direction: Initial direction (overridden by toolbar tool)
• Other ChakraProvider props: Passed directly to ChakraBaseProvider

Theme Extension:

The decorator extends themes using Chakra UI's extendTheme:

const themeWithDirectionOverride = React.useMemo(() => {
  return chakraTheme
    ? extendTheme({ direction }, chakraTheme)
    : extendTheme({ direction });
}, [chakraTheme, direction]);

Event Communication

The provider system uses Storybook's channel-based event system for communication between toolbar tools and story decorators.

const EVENTS = {
  TOGGLE_COLOR_MODE: "@chakra-ui/storybook-addon/toggleColorMode",
  TOGGLE_DIRECTION: "@chakra-ui/storybook-addon/toggleDirection",
};

Event Flow:

1. User clicks toolbar tool (ColorModeTool or DirectionTool)
2. Tool emits event via addons.getChannel().emit()
3. Provider components listen for events via channel.on()
4. State updates trigger re-render with new theme/direction
5. Stories reflect the updated configuration