@storybook/addon-backgrounds

What is @storybook/addon-backgrounds?

The @storybook/addon-backgrounds package is a Storybook addon that allows developers to switch between different backgrounds for their components' preview in the Storybook UI. It is useful for visualizing how components look against different backgrounds and can be used to simulate different environments.

What are @storybook/addon-backgrounds's main functionalities?

Setting default backgrounds

This feature allows you to set default backgrounds that will be available for all stories. You can specify a default background that will be pre-selected when a story is loaded.

import { addParameters } from '@storybook/react';
addParameters({
  backgrounds: [
    { name: 'twitter', value: '#00aced', default: true },
    { name: 'facebook', value: '#3b5998' },
  ],
});

Configuring backgrounds for individual stories

This feature allows you to configure backgrounds for individual stories. You can override the default backgrounds for specific stories to tailor the background to the component's needs.

import { storiesOf } from '@storybook/react';
storiesOf('Button', module)
  .addParameters({
    backgrounds: [
      { name: 'dark', value: '#222222' },
      { name: 'light', value: '#eeeeee' },
    ],
  })
  .add('with text', () => <button>Click me</button>);

Other packages similar to @storybook/addon-backgrounds

@storybook/addon-knobs

The @storybook/addon-knobs package allows you to edit React props dynamically using the Storybook UI. It is similar to @storybook/addon-backgrounds in that it enhances the Storybook experience by allowing for real-time changes to the component's environment, but it focuses on props rather than backgrounds.

@storybook/addon-actions

The @storybook/addon-actions package can be used to display data received by event handlers in Storybook. It is similar to @storybook/addon-backgrounds in that it helps in visualizing and debugging components, but it focuses on capturing and displaying actions rather than changing backgrounds.

@storybook/addon-viewport

The @storybook/addon-viewport package allows you to adjust the viewport size and layout for responsive design testing within Storybook. While @storybook/addon-backgrounds changes the background behind components, @storybook/addon-viewport changes the size of the frame that the component is rendered within.

README

Storybook Addon Backgrounds

Storybook Addon Backgrounds can be used to change background colors inside the preview in Storybook.

Framework Support

Installation

Backgrounds is part of essentials and so is installed in all new Storybooks by default. If you need to add it to your Storybook, you can run:

npm i -D @storybook/addon-backgrounds

Configuration

Then, add following content to .storybook/main.js:

export default {
  addons: ['@storybook/addon-backgrounds'],
};

Usage

The usage is documented in the documentation.

Changelog

8.4.0

Storybook 8.4 comes with a ton of exciting new features designed to give you the best experience developing, testing, and debugging tests in the browser!

• ▶️ Unified UI for component testing
• 5️⃣ Svelte 5 and Svelte CSF support
• ⚛️ React Native Storybook 8 release
• 🏷️ Tags-based filtering to organize your Storybook
• 🫧 Dependency cleanup to reduce install footprint
• 💯 Hundreds more improvements

<details> <summary>List of all updates</summary>

• Addon Test: Adjust file exports to be ESM/CJS compatible - #29471, thanks @valentinpalkovic!
• Addon Test: Error when addon interactions exists - #29434, thanks @valentinpalkovic!
• Addon Test: Escape XML when converting ANSI to HTML in test errors - #29446, thanks @ghengeveld!
• Addon Test: Fix hiding stacktrace for assertion errors in test panel - #29458, thanks @ghengeveld!
• Addon Test: Improve Error Handling - #29476, thanks @valentinpalkovic!
• Addon Test: Improve postinstall script - #29479, thanks @yannbf!
• Addon Test: Improve unsupported vitest message - #29486, thanks @valentinpalkovic!
• Addon Test: Only register testing module in Vite projects - #29472, thanks @yannbf!
• Addon Test: Throttle Vitest progress updates more heavily - #29482, thanks @ghengeveld!
• Addon-docs, blocks: Prebundle dependencies - #29301, thanks @JReinhold!
• Addon-Test: Support for @vitest/browser v2.1.2 - #29407, thanks @strozw!
• Blocks: Prebundle es-toolkit - #29259, thanks @JReinhold!
• Builder-vite: Replace .at() call with [] in codegen - #29048, thanks @Chudesnov!
• CLI: Don't add @storybook/addon-links by default - #29177, thanks @tobiasdiez!
• CLI: Ensure .gitignore updated via CLI ends with a newline - #29124, thanks @3w36zj6!
• CLI: Fix yarn detection - #29448, thanks @ndelangen!
• CLI: Migrate from chalk to picocolors - #28262, thanks @43081j!
• CLI: Refactor NPMProxy error parsing logic - #29459, thanks @yannbf!
• ConfigFile: Fix export { X } parsing - #29344, thanks @vctqs1!
• Core: Add unified UI Testing Module - #29241, thanks @yannbf!
• Core: Close story status menu when selecting an item - #29455, thanks @ghengeveld!
• Core: Fix building Storybook deleting project root files - #29371, thanks @JReinhold!
• Core: Fix race condition during empty folder init - #29490, thanks @valentinpalkovic!
• Core: Make prettier an optional peer dependency - #29223, thanks @JReinhold!
• Core: Migrate from express to polka - #29230, thanks @43081j!
• Core: Migrate from qs to picoquery - #28315, thanks @43081j!
• Core: Open 'Component tests' addon panel when clicking a story status - #29456, thanks @ghengeveld!
• Core: Remove handlebars usage - #29208, thanks @ndelangen!
• Core: Remove dependence on file-system-cache - #29256, thanks @ndelangen!
• Core: Replace fs-extra with the native APIs - #29126, thanks @ziebam!
• Core: Replace lodash with es-toolkit - #28981, thanks @ndelangen!
• Core: Show checkmark icon in story status dropdown and update status label for component tests - #29451, thanks @ghengeveld!
• Core: Show tooltip on filter toggles to clarify their purpose - #29447, thanks @ghengeveld!
• Core: Track test provider state in sessionStorage - #29450, thanks @ghengeveld!
• Core: Upgrade esbuild, broadening version range - #29254, thanks @ndelangen!
• Dependencies: Upgrade VTA to v3.1.0 - #29449, thanks @ghengeveld!
• Dependencies: Upgrade VTA to v3.2.0 to resolve peerDep conflict - #29461, thanks @ghengeveld!
• Interactions: Escape xml of interactions errors - #29414, thanks @kasperpeulen!
• Maintenance: Fix broken and outdated documentation links - #29412, thanks @jonniebigodes!
• Manager: Add tags property to ComponentEntry objects - #29343, thanks @Sidnioulz!
• React: Prebundle all of renderers/react's dependencies - #29298, thanks @ndelangen!
• Svelte: Improve argTypes inference with svelte2tsx - support runes - #29423, thanks @JReinhold!
• Test: Remove unused util dependency - #29310, thanks @JReinhold!
• UI: Brand image css class conflict causes image to resize on hot reloads - #29129, thanks @ShreySinha02!
• UI: Fix RefIndicator to use CheckIcon instead of string - #29209, thanks @JSMike!
• UI: Simple tag filtering - #29333, thanks @shilman!
• UI: Use production-mode react in manager - #29197, thanks @ndelangen!
• Viewport-addon: Add InitialViewportKeys type to viewport addon - #29182, thanks @hyeongrok7874!
• Vite: Add jsdoc-type-pratt-parser to optimizeDeps - #29179, thanks @tobiasdiez!
• Vite: Cleanup and prebundle dependencies - #29302, thanks @JReinhold!
• Webpack: Fix export 'act' (imported as 'React4') was not found in 'react' errors in webpack - #29235, thanks @kasperpeulen!

</details>