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 them */
.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;