How do I make the canvas background color change, when a theme is selected?

[alexbjorlig]

Summary

I'm using Sveltekit and Tailwind, and followed the guide here to add the "theme" selector:

My question is, how can I make the background color of the canvas change to a dark tailwind class, when dark-mode is selected? Thanks 🙏

Additional information

No response

Create a reproduction

No response

[jonniebigodes]

Thanks for taking the time to reach out to us with your question. We appreciate it 🙏 ! So that you're aware, the styling addon you referred to is officially [deprecated}(https://storybook.js.org/addons/@storybook/addon-styling), and we're encouraging users to use one of the alternatives provided in the disclaimer (ie., @storybook/addon-styling-webpack and @storybook/addon-themes. Without any additional context on your environment, I'm guessing that what you're trying to do is more in line with the @storybook/addon-themes. And looking at the documentation for it. it seems that includes some documentation of how to configure Storybook with Tailwind. Can you take a look at it and let us know if it helped with your use case?

Looking forward to hearing from you.

Hope you have a great day.

Stay safe

[alexbjorlig]

Ok, so I refactored to @storybook/addon-themes and i now have the theme-selector working with this setup:

preview.ts

import type { Preview, SvelteRenderer } from '@storybook/svelte';
import { withThemeByClassName } from '@storybook/addon-themes';

import '../src/tailwind.css';

const preview: Preview = {
    parameters: {
        actions: { argTypesRegex: '^on[A-Z].*' },
        controls: {
            matchers: {
                color: /(background|color)$/i,
                date: /Date$/,
            },
        },
    },
    decorators: [
        withThemeByClassName<SvelteRenderer>({
            themes: {
                light: '',
                dark: 'dark',
            },
            defaultTheme: 'light',
        }),
    ],
};

export default preview;

main.ts

import { join, dirname } from 'path';
import type { StorybookConfig } from '@storybook/sveltekit';

/**
 * This function is used to resolve the absolute path of a package.
 * It is needed in projects that use Yarn PnP or are set up within a monorepo.
 */
function getAbsolutePath(value) {
    return dirname(require.resolve(join(value, 'package.json')));
}

/** @type { import('@storybook/sveltekit').StorybookConfig } */
const config: StorybookConfig = {
    stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
    addons: [
        getAbsolutePath('@storybook/addon-links'),
        getAbsolutePath('@storybook/addon-essentials'),
        getAbsolutePath('@storybook/addon-interactions'),
        '@storybook/addon-themes',
    ],
    framework: {
        name: '@storybook/sveltekit', //getAbsolutePath('@storybook/sveltekit'),
        options: {},
    },
    docs: {
        autodocs: 'tag',
    },
};
export default config;

However, I still don't get a dark background on the canvas when I select dark-mode?

[alexbjorlig]

Do you have any ideas what I could try @jonniebigodes - seems like a simple thing but can't find it in the docs?

[sindrisig]

I think i am having the same issue. I am trying to use both @storybook/addon-backgrounds and @storybook/addon-themes. I have defined

const parameters = {
  docs: {
    container: DocsContainer,
    page: DocsPage,
  },
  backgrounds: {
    default: 'Light Theme',
    values: [
      {
        name: 'Light Theme',
        value: '#ffffff',
      },
      {
        name: 'Dark Theme',
        value: '#000000',
      },
    ],
  },
};

Then i have a decorator using withThemeFromJSXProvider. I can change themes through the action bar and select light or dark theme. But what i am trying to figure out is how can i select a background color defined with addon-backgrounds when i change theme. A even better solution would be how can i remove the addon background colors and just actually change the full page background color through addon-themes.

[jaredmcateer]

FWIW I solved the issue of wanting different backgrounds colors based on themes by using CSS vars

In preview.tsx:

import { type Preview } from '@storybook/react';
import { withThemeFromJSXProvider } from '@storybook/addon-themes';
import { ThemeProvider, createUseStyles } from 'react-jss';

import { themes, ThemeName, type ThemeProperties } from '../src/styles/use-styles';

const useStyles = createUseStyles((theme: ThemeProperties) => ({
  '@global': {
    body: {
      '--light-bg': theme.name === ThemeName.LIGHT ? '#f1f1f1' : '#fafafb',
      '--dark-bg': theme.name === ThemeName.LIGHT ? '#141414' : '#000000',
      '--brand-bg': theme.primaryBg,
    },
  },
}));

const GlobalStyles: React.FC = () => {
  useStyles();
  return <></>;
};

const preview: Preview = {
  // ...
  decorators: [
    withThemeFromJSXProvider({
      themes,
      defaultTheme: ThemeName.DARK,
      Provider: ThemeProvider,
      GlobalStyles,
    }),
    // ...
  ],
  parameters: {
    backgrounds: {
      default: 'light-bg',
      values: [
        {
          name: 'light-bg',
          value: 'var(--light-bg)',
        },
        {
          name: 'dark-bg',
          value: 'var(--dark-bg)',
        },
        {
          name: 'brand-bg',
          value: 'var(--brand-bg)',
        },
      ],
    },
  },
};

[chantastic]

Using Tailwind with add on-theme, my preference is to use preview-body.html to add responsive background classes to thee Preview Body element: https://storybook.js.org/docs/sharing/storybook-composition

[alexbjorlig]

I currently added this to .storybook/preview-body.html

<html>
    <body class="dark:bg-gray-800"></body>
</html>

But it gives a quick-flash when loading stories?

[pipech]

Adding body tag to .storybook/preview-body.html does work perfectly for me. (You might need to add those class to tailwind safe-listing classes)

<body class="dark:bg-blue-500 bg-red-500"></body>

[pawelgalazka]

There is actually a quite easy way to do this, with themes addon alone:

export const decorators = [
  withThemeByClassName({
    themes: {
      light: "light",
      dark: "dark bg-neutral-900",
    },
    defaultTheme: "light",
  }),
]

Just add Tailwind background class as part of your themes css classes list.

Be mindful that in tailwindcss.config.ts you need to add ".storybook/preview.ts" to your content config prop, so Tailwind can read bg-neutral-900 class.

Might be worth also disabling backgrounds in your preview config:

const preview: Preview = {
  parameters: {
    backgrounds: { disable: true },
  }
}

as they will be conflicting with your theme classes.

[arnoldsandoval]

This works great, but for some reason it doesnt work in the docs addon for me. Any idea why this might be?

For some reason it doesnt apply the background color to the preview, or the entire docs page and im unsure why

link to storybook

[leonp-s]

I have also been struggling with this. Wondering if there is some kind of workaround.

[atomicrobokid]

@arnoldsandoval @leonp-s - sounds like you are having the same issue as me that I raised in a separate discussion

I've got it working (changing the background, font etc to my design systems theme) by a little workaround #28495

[arnoldsandoval]

@atomicrobokid no idea how I missed this, but I got it working in storybook 8 with a few modifications. Posted the updated code that worked for me in #28495

Thank you! 🙏

[shadiramadan]

For those in tailwindcss land I got it working with this from inspiration from everyone else!

  parameters: {
    backgrounds: {
      options: {
        "light/dark": {
          name: "light/dark",
          value: "var(--light-dark)",
        },
        white: { name: "white", value: "#ffffff" },
        "gray-50": { name: "gray-50", value: "#f7f7f7" },
        "gray-950": { name: "gray-950", value: "#292929" },
      },
    },
  },
  initialGlobals: {
    backgrounds: {
      value: "light/dark",
    },
  },
  decorators: [
    withThemeByClassName({
      themes: {
        light: "light [--light-dark:#ffffff]", // gray-50
        dark: "dark [--light-dark:#292929]", // gray-950
      },
      defaultTheme: "light",
    }),

As someone else mentioned- make sure your tailwind config is looking at this file!

[mmospanenko]

Doesn't work. Interesting that so popular tool can't do so simple and logical thing - just apply dark background in dark mode...

[jjvanherpen]

I was looking for the same solution but couldn’t find anything anywhere. Eventually, I created this, but it’s a bit buggy. I’m not sure if anyone has a better solution.

import type { Preview } from '@storybook/vue3';
import '../src/assets/theme.scss';
import '../src/assets/main.css';
import { ref } from 'vue';

export const globalTypes = {
  theme: {
    name: 'Theme',
    description: 'Toggle light/dark mode',
    defaultValue: 'light',
    toolbar: {
      icon: 'contrast',
      dynamicTitle: true,
      items: [
        { value: 'light', title: 'Light' },
        { value: 'dark', title: 'Dark' },
      ],
    },
  },
};

export const decorators = [
  (story, context) => {
    const theme = ref(context.globals.theme);
    if(theme.value === 'dark'){
        context.userGlobals.backgrounds.value = '#282828';
    }else if(theme.value === 'light'){
        context.userGlobals.backgrounds.value = '#ffffff';
    }
    return {
      components: { story },
      template: `
        <div :class="theme">
          <story />
        </div>
      `,
      setup() {
        return { theme };
      },
    };
  },
];

const preview: Preview = {
  parameters: {
    backgrounds: {
      default: 'Light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'Dark', value: '#282828' },
      ],
    },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

export default preview;

[sudomaxime]

The only way I could reliably find to make it work is by making a decorator like this:

export const ThemeSwitchDecorator: Decorator = (Story, context) => {
  const { scheme, viewMode } = context.globals;
  const isIframe = viewMode === "story";
  const darkmodeBackgroundColor = "black";

  function WithColor(props: {
    children: React.ReactNode;
    themeClassName: string;
  }) {
    return (
      <div
        style={{
          padding: context.viewMode == "docs" ? "30px" : "15px",
          backgroundColor:
            props.themeClassName === "dark" ? darkmodeBackgroundColor : "white",
          width: "100%",
        }}
        className={`${props.themeClassName}`}
      >
        {props.children}
      </div>
    );
  }

  if (scheme === "light") {
    return (
      <WithColor themeClassName="light">
        <Story />
      </WithColor>
    );
  }

  if (scheme === "dark") {
    return (
      <WithColor themeClassName="dark">
        <div
          style={{
            position: "fixed",
            width: "100%",
            height: context.viewMode == "docs" ? "100%" : "100vh",
            backgroundColor: darkmodeBackgroundColor,
            left: 0,
            top: 0,
          }}
        ></div>
        <Story />
      </WithColor>
    );
  }

  return (
    <>
      <div
        style={{
          display: "flex",
          width: "100%",
          height: context.viewMode == "docs" ? "100%" : "100vh",
        }}
      >
        <WithColor themeClassName="light">
          <Story />
        </WithColor>
        <WithColor themeClassName="dark">
          <Story />
        </WithColor>
      </div>
    </>
  );
};

And also setting the fullscreen parameter in preview:

const preview: Preview = {
  parameters: {
    layout: "fullscreen", // <----- here
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

[longzheng]

I'm using Tailwind and CSS variables for dark mode (based on shadcn) and I came up with this solution

Screen.Recording.2025-01-21.165312.mp4

My index.css has the light/dark mode background colors defined with the CSS variable --background

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    ...
  }

  .dark {
    --background: 222.2 84% 4.9%;
    ...
  }
}

My tailwind.config.ts specifies a background color using the CSS variable --background

import type { Config } from 'tailwindcss';
import tailwindCssAnimate from 'tailwindcss-animate';

export default {
    darkMode: [`class`],
    theme: {
        extend: {
            colors: {
                background: `hsl(var(--background))`,

I update the Storybook preview.tsx to override the doc canvas background color with the tailwind class bg-background with an important override (since the base class has a background).

const preview: Preview = {
    ...
    parameters: {
        controls: {
            matchers: {
                color: /(background|color)$/i,
                date: /Date$/i,
            },
        },
        docs: {
            canvas: {
                // override the canvas background based on the theme
                className: `!bg-background`,
            },
        },
    },
};

I also have to add the class to the tailwind.config.ts Tailwind safelisting since the Storybook preview is not being scanned by Tailwind.

export default {
    ...
    safelist: [
        // allow Storybook to override the canvas background based on the theme
        `!bg-background`,
    ]

[longzheng]

Alternatively without Tailwind or adding the safelist class it's also possible to inject a custom CSS module into preview.tsx

So I create a .storybook/storybook.css with

/* override icon gallery background based on theme */
.docblock-icongallery>div>div:first-child {
    background: hsl(var(--background))
}

/* override story canvas background based on theme */
.sbdocs-preview {
    background: hsl(var(--background)) !important
}

Then I just put it in preview.tsx

import '@/index.css';
import './storybook.css';

const preview: Preview = {
...
}

export default preview;

[binhtran04]

Thanks! This is helful

[cvillard-mia]

This helped a ton, thank you!

[drusellers]

I need to solve the "order of operations" issue.

1. in preview.tsx I import my tailwind file

import {withThemeByClassName} from "@storybook/addon-themes";

// brings in tailwind css
import '../css/index.css'

const preview = {
  parameters: {
    backgrounds: {disable: true},
  },
  decorators: [
    withThemeByClassName({
      themes: {
        light: '',
        dark: 'dark'
      },
      defaultTheme: 'light'
    }),
  ],
}

export default preview

2. in preview-head.html I set the body background color

<!-- Adding files to the preview-head.html will include the necessary files when viewing components through Storybook -->
<!-- Pull in static files served from your Static directory or the internet -->

<style>
    .dark body {
        /* var(--color-gray-950) */
        background: #0F0F0F;
    }
</style>

Now I just need to figure out the order of operations so that I can use my actual "var" from Tailwind but I'm happy with this for now. Thank you everyone for sharing your ideas.

[toppsdown]

I'm new to storybook, and I just spent 3 hours trying to get dark mode to work properly. It works on stories, but not autodocs. Couldn't make it happen so eventually just gave up. Kinda disappointing that such a popular tool like storybook doesn't have straightforward support for dark mode, one of the most basic use cases of every website.

[praveentcom]

Did you figure it out? Stuck on the same boat.

[johan44co]

This works for me

[jceb]

@johan44co Awesome, this works well. Here's the full config:

main.js:

import { defineMain } from "... your framework"; // INFO: this is different for you config

export default defineMain({
  // framework: .. // INFO: this is different for you config
  addons: [
    "@storybook/addon-onboarding",
    "@storybook/addon-docs",
    "@storybook/addon-a11y",
    "@storybook/addon-links",
    "@storybook/addon-vitest",
    "@storybook/addon-themes", // INFO: this part is relevant! provides a theme switcher for components see https://storybook.js.org/addons/@storybook/addon-themes
    "@vueless/storybook-dark-mode", // INFO: helpful if you also want to switch storybook's UI theme. provides a theme switcher for storybook's UI, not the component's UI, see https://storybook.js.org/addons/@vueless/storybook-dark-mode
  ],
  stories: [
    "../stories/**/*.mdx",
    "../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)",
  ],
});

`preview.js:

import addonA11y from "@storybook/addon-a11y";
import addonDocs from "@storybook/addon-docs";
import { definePreview, Renderer } from "... your framework";
import { withThemeByClassName } from "@storybook/addon-themes";

export default definePreview({
  addons: [addonDocs(), addonA11y()],
  parameters: {
    // automatically create action args for all props that start with 'on'
    actions: {
      argTypesRegex: "^on.*",
    },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    a11y: {
      // 'todo' - show a11y violations in the test UI only
      // 'error' - fail CI on a11y violations
      // 'off' - skip a11y checks entirely
      test: "todo",
    },
  },
  decorators: [ // INFO: this part is relevant to display the theme switcher button
    withThemeByClassName<Renderer>({
      themes: {
        light: "",
        dark: "dark",
      },
      defaultTheme: "light",
    }),
  ],
  // All components will have an automatically generated Autodocs entry: https://storybook.js.org/docs/writing-docs/autodocs
  // tags: ['autodocs'],
});

preview-body.html (it's also possible to place everything inside the main.ts file: https://storybook.js.org/docs/api/main-config/main-config-preview-body):

<html>
  <head>
    <style>
      body {
        background: var(--background);
      }
      :root {
        --background: #fdfdfd;
      }
      :root:where(.dark, .dark *) {
        --background: #1a1a1a;
      }
    </style>
  </head>
  <body></body>
</html>

[johan44co]

@jceb I decided to have more control over the implementation and mimic some custom behaviour that I expect once the components are implemented, like keeping the saved theme on local storage and checking the system's current theme.

This is how it looks:

here is the code:

@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));

:root {
  --background: #ffffff;
  --foreground: #111827;
}

:root:where(.dark, .dark *) {
  --background: #111827;
  --foreground: #ffffff;
}

body {
  background: var(--background);
  color: var(--foreground);
}

import { Preview } from '@storybook/nextjs';
import { Decorator } from '@storybook/react';
import { useEffect } from 'react';

import '../src/app/globals.css';

// Custom decorator to handle theme based on localStorage and system preference
const withTheme: Decorator = (Story, context) => {
  const theme = context.globals.theme;

  useEffect(() => {
    const applyTheme = () => {
      let isDark: boolean;

      if (theme === 'dark') {
        isDark = true;
        localStorage.theme = 'dark';
      } else if (theme === 'light') {
        isDark = false;
        localStorage.theme = 'light';
      } else {
        // 'system' or undefined - respect system preference
        localStorage.removeItem('theme');
        isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
      }
      
      document.documentElement.classList.toggle('dark', isDark);
    };

    applyTheme();

    // Listen for system preference changes when in system mode
    if (!theme || theme === 'system') {
      const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
      const handleMediaChange = () => applyTheme();
      
      mediaQuery.addEventListener('change', handleMediaChange);
      return () => mediaQuery.removeEventListener('change', handleMediaChange);
    }
  }, [theme]);

  return Story();
};

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
       color: /(background|color)$/i,
       date: /Date$/i,
      },
    },
  },
  globalTypes: {
    theme: {
      description: 'Global theme for components',
      defaultValue: 'system',
      toolbar: {
        title: 'Theme',
        icon: 'circlehollow',
        items: [
          { value: 'light', icon: 'sun', title: 'Light' },
          { value: 'dark', icon: 'moon', title: 'Dark' },
          { value: 'system', icon: 'browser', title: 'System' },
        ],
        dynamicTitle: true,
      },
    },
  },
  decorators: [
    withTheme,
  ],
};

export default preview;

[connorwforsyth]

I tried a bunch of things in the thread.

What finally worked for me (fairly simple)... was to:

1. create a .storybook/preview-head.html file. and add the following code:

<style>
   .docs-story {
        background-color: var(--background);
    }
</style>

This is specifically targeting the docs-story canvas element.

That's it. Note I'm using shadcn.

Hope this helps you. : )

[connorwforsyth]

Here is my preview.ts for reference:

import type { Preview } from "@storybook/react-vite";
import { withThemeByClassName } from "@storybook/addon-themes";
import "@/styles/globals.css";

const preview: Preview = {

  parameters: {
    backgrounds: { 
      disable: true
    },
    layout: "centered",
    controls: {
      expanded: true,
    },
  },

  decorators: [
    withThemeByClassName({
      themes: {
        light: "light",
        dark: "dark",
      },
      defaultTheme: "light",
    }),
  ],
};

export default preview;