mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-09 00:19:13 +08:00
278 lines
8.8 KiB
Plaintext
278 lines
8.8 KiB
Plaintext
---
|
|
title: 'Backgrounds'
|
|
sidebar:
|
|
order: 2
|
|
title: Backgrounds
|
|
---
|
|
|
|
The backgrounds toolbar addon allows you to set the background color on which the story renders in the UI:
|
|
|
|
<Video src="../_assets/essentials/addon-backgrounds-optimized.mp4" />
|
|
|
|
## Configuration
|
|
|
|
By default, the backgrounds toolbar includes a light and dark background.
|
|
|
|
But you're not restricted to these backgrounds. You can configure your own set of colors with the `backgrounds` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering). There are two ways to configure the backgrounds:
|
|
|
|
### Using `options`
|
|
|
|
<Callout variant="info">
|
|
This API can only be used when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
The available background colors are defined using the `options` property:
|
|
|
|
{/* prettier-ignore-start */}
|
|
|
|
<CodeSnippets path="addon-backgrounds-options-in-preview.md" />
|
|
|
|
{/* prettier-ignore-end */}
|
|
|
|
### Using `values`
|
|
|
|
If you're not using the `globals` API, you can define the available background colors using the `values` property:
|
|
|
|
{/* prettier-ignore-start */}
|
|
|
|
<CodeSnippets path="addon-backgrounds-values-in-preview.md" />
|
|
|
|
{/* prettier-ignore-end */}
|
|
|
|
With either method, available backgrounds can be defined at the project, component, and story levels.
|
|
|
|
To apply a default background color, assign the `default` property to one of the available colors.
|
|
|
|
## Overriding the background for a story
|
|
|
|
The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can force a story to use a specific background color. There are two ways to do this, which have different behaviors:
|
|
|
|
### Using `globals`
|
|
|
|
<Callout variant="info">
|
|
This feature is available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
When you specify a background color for a story (or a component's stories) using `globals`, the background color is applied and cannot be changed using the toolbar. This is useful when you want to ensure that a story is always rendered on a specific background color.
|
|
|
|
{/* prettier-ignore-start */}
|
|
|
|
<CodeSnippets path="addon-backgrounds-override-globals.md" usesCsf3 />
|
|
|
|
{/* prettier-ignore-end */}
|
|
|
|
### Using `parameters`
|
|
|
|
If you're not yet using the `globals` API, you can set the default background color for a story using the `parameters.backgrounds.default` parameter:
|
|
|
|
{/* prettier-ignore-start */}
|
|
|
|
<CodeSnippets path="addon-backgrounds-override-parameters-default.md" usesCsf3 />
|
|
|
|
{/* prettier-ignore-end */}
|
|
|
|
As implied by the name, this method only sets the default background color for a story. You can still change the background color using the toolbar when viewing the story.
|
|
|
|
## Extending the configuration
|
|
|
|
You can also define backgrounds per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.mdx#component-parameters).
|
|
|
|
### Using `options`
|
|
|
|
<Callout variant="info">
|
|
This API can only be used when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
The available background colors are defined using the `options` property. In this example, we'll adjust the colors for all of the Button component's stories:
|
|
|
|
{/* prettier-ignore-start */}
|
|
|
|
<CodeSnippets path="addon-backgrounds-options-in-meta.md" />
|
|
|
|
{/* prettier-ignore-end */}
|
|
|
|
### Using `values`
|
|
|
|
If you're not using the `globals` API, you can define the available background colors using the `values` property. In this example, we'll adjust the colors for all of the Button component's stories:
|
|
|
|
{/* prettier-ignore-start */}
|
|
|
|
<CodeSnippets path="addon-backgrounds-values-in-meta.md" />
|
|
|
|
{/* prettier-ignore-end */}
|
|
|
|
## Disable backgrounds
|
|
|
|
If you want to turn off backgrounds in a story, you can do so by setting the `backgrounds` parameter like so:
|
|
|
|
<Callout variant="info">
|
|
Note that the property name changes when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
{/* prettier-ignore-start */}
|
|
|
|
<CodeSnippets path="addon-backgrounds-disabled.md" usesCsf3/>
|
|
|
|
{/* prettier-ignore-end */}
|
|
|
|
## Grid
|
|
|
|
The Backgrounds toolbar also includes a Grid selector, which allows you to quickly see if your components are aligned.
|
|
|
|
You don't need additional configuration to get started. But its properties are fully customizable; if you don't supply any value to any of its properties, they'll default to the following values:
|
|
|
|
{/* prettier-ignore-start */}
|
|
|
|
<CodeSnippets path="addon-backgrounds-grid.md" />
|
|
|
|
{/* prettier-ignore-end */}
|
|
|
|
## API
|
|
|
|
### Globals
|
|
|
|
This addon contributes the following globals to Storybook, under the `backgrounds` namespace:
|
|
|
|
<Callout variant="info">
|
|
These globals are only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
#### `grid`
|
|
|
|
Type: Boolean
|
|
|
|
Whether the [grid](#grid) is displayed.
|
|
|
|
#### `value`
|
|
|
|
Type: `string`
|
|
|
|
When set, the background color is applied and cannot be changed using the toolbar. Must match the key of one of the [available colors](#using-options).
|
|
|
|
### Parameters
|
|
|
|
This addon contributes the following [parameters](../writing-stories/parameters.mdx) to Storybook, under the `backgrounds` namespace:
|
|
|
|
#### `default`
|
|
|
|
Type: `string`
|
|
|
|
Required: See description
|
|
|
|
Default background color. Must match the `name` property of one of the [available colors](#values).
|
|
|
|
#### `disable`
|
|
|
|
<Callout variant="info">
|
|
This API is deprecated when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
Type: `boolean`
|
|
|
|
Turn off this addon's behavior. If you wish to turn off this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.mdx#disabling-addons) for more information.
|
|
|
|
This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level.
|
|
|
|
#### `disabled`
|
|
|
|
<Callout variant="info">
|
|
This API is only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
Type: `boolean`
|
|
|
|
Turn off this addon's behavior. If you wish to turn off this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.mdx#disabling-addons) for more information.
|
|
|
|
This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level.
|
|
|
|
#### `grid`
|
|
|
|
Type:
|
|
|
|
```ts
|
|
{
|
|
cellAmount?: number;
|
|
cellSize?: number;
|
|
disable?: boolean;
|
|
offsetX?: number;
|
|
offsetY?: number;
|
|
opacity?: number;
|
|
}
|
|
```
|
|
|
|
Configuration for the [background grid](#grid).
|
|
|
|
##### `grid.cellAmount`
|
|
|
|
Type: `number`
|
|
|
|
Default: `5`
|
|
|
|
Specify the size of the minor grid lines.
|
|
|
|
##### `grid.cellSize`
|
|
|
|
Type: `number`
|
|
|
|
Default: `20`
|
|
|
|
Specify the size of the major grid lines.
|
|
|
|
##### `grid.disable`
|
|
|
|
Type: `boolean`
|
|
|
|
Turn off the grid.
|
|
|
|
##### `grid.offsetX`
|
|
|
|
Type: `number`
|
|
|
|
Default: `0` if [story layout](../api/parameters.mdx#layout) is `'fullscreen'`; `16` if story layout is `'padded'`
|
|
|
|
Horizontal offset of the grid.
|
|
|
|
##### `grid.offsetY`
|
|
|
|
Type: `number`
|
|
|
|
Default: `0` if [story layout](../api/parameters.mdx#layout) is `'fullscreen'`; `16` if story layout is `'padded'`
|
|
|
|
Vertical offset of the grid.
|
|
|
|
##### `grid.opacity`
|
|
|
|
Type: `number`
|
|
|
|
Default: `0.5`
|
|
|
|
The opacity of the grid lines.
|
|
|
|
#### `options`
|
|
|
|
<Callout variant="info">
|
|
This API is only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
Type: `Record<string, { name: string; value: string }>`
|
|
|
|
Required: See description
|
|
|
|
Defines the background colors. See above for a [usage example](#with-options).
|
|
|
|
Required when defining `backgrounds` parameter at project level.
|
|
|
|
#### `values`
|
|
|
|
<Callout variant="info">
|
|
This API is deprecated when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
|
|
</Callout>
|
|
|
|
Type: `{ name: string; value: string }[]`
|
|
|
|
Required: See description
|
|
|
|
Available background colors. See above for a [usage example](#using-values).
|
|
|
|
Required when defining `backgrounds` parameter at project level.
|