ColorPalette props
ColorPalette accepts the following props: children (type: React.ReactNode, required) - ColorPalette expects only ColorItem children.
Storybook · API · all subjects
doc-blocks
124 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
ColorItem props reference
ColorItem is imported from '@storybook/addon-docs/blocks' and is configured with three required props: colors (type: string[] | { [key: string]: string }) - provides the list of colors to be displayed in any valid CSS color format (hex, RGB, HSL) or gradients like 'linear-gradient(to right, white, black)', keys are displayed above values when object is provided; subtitle (type: string) - provides an additional description of the color; title (type: string) - sets the name of the color to be displayed.
ColorPalette block usage
The ColorPalette block allows you to document all color-related items such as swatches used throughout your project. It is imported from '@storybook/addon-docs/blocks' and expects only ColorItem children.
ColorItem example with multiple formats
Example of ColorItem with various color formats: ```mdx import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks'; <Meta title="Colors" /> <ColorPalette> <ColorItem title="theme.color.greyscale" subtitle="Some of the greys" colors={{ White: '#FFFFFF', Alabaster: '#F8F8F8', Concrete: '#F3F3F3' }} /> <ColorItem title="theme.color.primary" subtitle="Coral" colors={{ WildWatermelon: '#FF4785' }} /> <ColorItem title="theme.color.positive" subtitle="Green" colors={{ Apple: 'rgba(102,191,60,1)', Apple80: 'rgba(102,191,60,.8)', Apple60: 'rgba(102,191,60,.6)', Apple30: 'rgba(102,191,60,.3)', }} /> <ColorItem title="gradient" subtitle="Grayscale" colors={{ Gradient: 'linear-gradient(to right,white,black)', }} /> <ColorItem title="gradient" subtitle="Grayscale" colors={['linear-gradient(65deg,white,black)']} /> </ColorPalette> ``` This example shows ColorItem supporting hex colors, rgba colors with varying opacity, and gradients in both object and array formats.
Canvas block usage with of prop
When using the Canvas block in MDX, it references a story with the `of` prop, which accepts a story export from a CSF file.
Canvas block withToolbar prop
The `withToolbar` prop accepts a boolean. Default: parameters.docs.canvas.withToolbar. Determines whether to render a toolbar containing tools to interact with the story.
Canvas block source prop
The `source` prop accepts SourceProps['code'] | SourceProps['format'] | SourceProps['language'] | SourceProps['type']. Specifies the props passed to the inner Source block. The dark prop is ignored, as the Source block is always rendered in dark mode when shown as part of a Canvas block.
Canvas block props derive defaults from parameters
Like most blocks, the Canvas block is configured with props in MDX. Many of those props derive their default value from a corresponding parameter in the block's namespace, parameters.docs.canvas.
Canvas block meta prop
The `meta` prop accepts CSF file exports (the full set of exports from the CSF file, not the default export). Specifies the CSF file to which the story is associated. You can render a story from a CSF file that you haven't attached to the MDX file (via Meta) by using the meta prop.
Canvas block sourceState prop
The `sourceState` prop accepts 'hidden' | 'shown' | 'none'. Default: parameters.docs.canvas.sourceState or 'hidden'. Specifies the initial state of the source panel. 'hidden': the source panel is hidden by default. 'shown': the source panel is shown by default. 'none': the source panel is not available and the button to show it is not rendered.
Canvas block additionalActions example
Example of using additionalActions prop in Canvas block: ```mdx import { Meta, Story, Canvas, SourceState } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; <Meta of={ButtonStories} /> <Canvas additionalActions={[ { title: 'Open in GitHub', onClick: () => { window.open( 'https://github.com/storybookjs/storybook/blob/next/code/ui/blocks/src/examples/Button.stories.tsx', '_blank', ); }, }, ]} of={ButtonStories.Primary} /> ```
Canvas block wraps Story with toolbar
The Canvas block is a wrapper around a Story, featuring a toolbar that allows you to interact with its content while automatically providing Source snippets.
Canvas block meta prop example
Example of using meta prop to render a story from a different CSF file: ```mdx import { Meta, Canvas } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; import * as HeaderStories from './Header.stories'; <Meta of={ButtonStories} /> {/* Although this MDX file is largely concerned with Button, it can render Header stories too */} <Canvas of={HeaderStories.LoggedIn} meta={HeaderStories} /> ```
Canvas block story prop
The `story` prop accepts StoryProps['inline'] | StoryProps['height'] | StoryProps['autoplay']. Specifies the props passed to the inner Story block.
Canvas block className prop
The `className` prop accepts a string. Default: parameters.docs.canvas.className. Provides HTML class(es) to the preview element for custom styling.
Canvas block deprecated children usage
In previous versions of Storybook it was possible to pass in arbitrary components as children to Canvas. That is deprecated and the Canvas block now only supports a single story.
Canvas block additionalActions prop
The `additionalActions` prop accepts an array of objects with shape: Array<{ title: string | JSX.Element; className?: string; onClick: () => void; disabled?: boolean; }>. Default: parameters.docs.canvas.additionalActions. Provides any additional custom actions to show in the bottom right corner as simple buttons that execute the onClick function.
Canvas block imports location
The Canvas block is imported from '@storybook/addon-docs/blocks'.
Canvas block layout prop
The `layout` prop accepts 'centered' | 'fullscreen' | 'padded'. Default: parameters.layout or parameters.docs.canvas.layout or 'padded'. Specifies how the canvas should layout the story. 'centered' centers the story within the canvas. 'padded' (default) adds padding to the story. 'fullscreen' shows the story as-is, without padding. The Canvas block will respect the parameters.layout value that defines how a story is laid out in the regular story view.
Controls of parameter
Type: Story export or CSF file exports. Specifies which story to retrieve controls from. If a CSF file exports object is provided, the primary (first) story in the file is used.
Controls block vs ArgTypes block
The Controls block shows a dynamic table of args with interactive controls. The ArgTypes block shows a static table of arg types with no controls. Use ArgTypes for displaying component interfaces without interactivity.
Controls block MDX example
import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; <Meta of={ButtonStories} /> <Canvas of={ButtonStories.Primary} /> <Controls of={ButtonStories.Primary} /> This example shows typical Controls block usage in an MDX doc file, rendering controls for the Primary story from Button.stories.
Controls sort parameter
Type: 'none' | 'alpha' | 'requiredFirst'. Default: parameters.docs.controls.sort or 'none'. Specifies control sort order. 'none' shows unsorted order as processed. 'alpha' sorts alphabetically by arg type name. 'requiredFirst' sorts alphabetically with required controls shown first.
Controls include parameter
Type: string[] | RegExp. Default: parameters.docs.controls.include. Specifies which controls to include in the args table. Only controls whose names match the regex or are in the array will be displayed.
Controls exclude parameter
Type: string[] | RegExp. Default: parameters.docs.controls.exclude. Specifies which controls to exclude from the args table. Controls whose names match the regex or are in the array will be omitted.
Controls block configuration with parameters
Controls block props can derive default values from corresponding parameters in the 'parameters.docs.controls' namespace. Props and parameters can be mixed, with props taking precedence.
Controls block requires inline stories enabled
The Controls doc block only provides functioning UI controls if inline stories are enabled. Inline stories can be controlled with the 'inline' configuration option.
Controls block purpose
The Controls block shows a dynamic table of args for a story, allowing documentation of its interface and runtime modification of args when used with the Story or Canvas blocks.
Controls doc block import
The Controls block is imported from '@storybook/addon-docs/blocks'.
JSDoc comments recommended for descriptions
JSDoc comments are recommended for descriptions, and parameters.docs.description.X properties should only be used in situations where comments are not possible to write, or where you want the description shown in Storybook to be different from the comments. Comments provide a better writing experience as you don't have to worry about indentation and are more discoverable for other developers exploring the story/component sources.
Description block example
Example of using the Description block in MDX: ```mdx import { Meta, Description } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; <Meta of={ButtonStories} /> <Description of={ButtonStories.Primary} /> ``` The first Description block shows the description for the default export (the meta). If that didn't have any comments, it would show the comments from the component instead. The second Description block shows the description for the Primary story export.
Description via parameters property
Descriptions can be specified in parameters. To describe a story via parameters instead of JSDoc comments, add it to parameters.docs.description.story. To describe meta/component, add it to parameters.docs.description.component.
Description lookup order for components
When documenting a component by referencing a meta export in the 'of' prop, the Description block looks for descriptions in this order: 1) parameters.docs.description.component in the meta, 2) JSDoc comments above the meta, 3) JSDoc comments above the component.
Description lookup order for stories
When documenting a story by referencing a story export in the 'of' prop, the Description block looks for descriptions in this order: 1) parameters.docs.description.story in the story, 2) JSDoc comments above the story.
Description block of prop
The Description block is configured with an 'of' prop. Type: Story export or CSF file exports. This prop specifies where to pull the description from, pointing to either a story or a meta depending on which description you want to show. Descriptions are pulled from JSDoc comments or parameters and rendered as markdown.
Description block import
The Description block is imported from '@storybook/addon-docs/blocks'.
Description block displays JSDoc comments
The Description block displays the description for a component, story, or meta, obtained from their respective JSDoc comments.
MDX2 does not handle imported markdown directly
Importing markdown files directly into MDX and referencing them as JSX will not work. This is because MDX2 has strict syntactical differences from plain markdown. MDX2 will try to evaluate certain content as JSX expressions, such as curly braces and angle brackets. Additionally, MDX2 wraps strings on newlines in p tags or similar elements, causing content to render differently than in a plain markdown file.
Markdown block usage example
Example of using the Markdown block in an MDX file: ```mdx import ReadMe from './README.md?raw'; import { Markdown } from '@storybook/addon-docs/blocks'; # A header <Markdown>{ReadMe}</Markdown> ```
Markdown block import statement
The Markdown block is imported from '@storybook/addon-docs/blocks' with the statement: `import { Markdown } from '@storybook/addon-docs/blocks';`
Markdown block import path requires ?raw suffix
When importing markdown files for use with the Markdown block, you must use the ?raw suffix on the import path to ensure the content is imported as-is and isn't being evaluated. For example, use `import ReadMe from './README.md?raw';` instead of `import ReadMe from './README.md';`
Markdown block options prop
The Markdown block accepts an 'options' prop that specifies options passed to the underlying markdown-to-jsx library.
Markdown block children prop
The Markdown block accepts a 'children' prop of type string that provides the markdown-formatted string to parse and display.
IconItem children prop
IconItem has a children prop of type React.ReactNode that provides the icon to be displayed.
IconItem name prop
IconItem has a required name prop of type string that sets the name of the icon.
IconItem block import
IconItem is imported from '@storybook/addon-docs/blocks'.
IconGallery children prop
IconGallery has a children prop of type React.ReactNode. It expects only IconItem children.
IconGallery block import
IconGallery is imported from '@storybook/addon-docs/blocks'.
IconGallery purpose
IconGallery is a doc block that enables documentation of React icon components associated with a project, displayed in a neat grid.
IconGallery automated icon documentation example
Example showing how to automate icon documentation by wrapping IconItem in a loop to iterate over multiple icons: import { Meta, IconGallery, IconItem } from '@storybook/addon-docs/blocks'; import { Icon as IconExample } from './Icon'; import * as icons from './icons'; # Iconography <IconGallery> {Object.keys(icons).map((icon) => ( <IconItem name={icon}> <IconExample icon={icon} /> </IconItem> ))} </IconGallery>
IconGallery basic usage example
Example showing how to use IconGallery with IconItem to document a set of icon components: import { Meta, IconGallery, IconItem } from '@storybook/addon-docs/blocks'; import { Icon as IconExample } from './Icon'; <Meta title="Iconography" /> # Iconography <IconGallery> <IconItem name="mobile"> <IconExample name="mobile" /> </IconItem> <IconItem name="user"> <IconExample name="user" /> </IconItem> <IconItem name="browser"> <IconExample name="browser" /> </IconItem> <IconItem name="component"> <IconExample name="component" /> </IconItem> <IconItem name="calendar"> <IconExample name="calendar" /> </IconItem> <IconItem name="paintbrush"> <IconExample name="paintbrush" /> </IconItem> <IconItem name="add"> <IconExample name="add" /> </IconItem> <IconItem name="subtract"> <IconExample name="subtract" /> </IconItem> <IconItem name="document"> <IconExample name="document" /> </IconItem> <IconItem name="graphline"> <IconExample name="graphline" /> </IconItem> </IconGallery>
Meta title prop
The title prop is a string that sets the title of an unattached MDX file and controls its location in the sidebar.
Meta of prop
The of prop accepts CSF file exports and specifies which CSF file is attached to the MDX file. Pass the full set of exports from the CSF file, not the default export. This prop is optional; if omitted, you can use the title prop to control location or let autotitle decide.
Meta name prop
The name prop is a string that sets the name of the attached doc entry. You can attach more than one MDX file to the same component in the sidebar by setting different names for each file's Meta.
Meta isTemplate prop
The isTemplate prop is a boolean that determines whether the MDX file serves as an automatic docs template. When true, the MDX file is not indexed as it normally would be.
Meta block import
The Meta block is imported from '@storybook/addon-docs/blocks'.
Meta block purpose and usage
The Meta block is used to attach a custom MDX docs page alongside a component's list of stories, or to control the location of unattached docs entries in the sidebar. It doesn't render any visible content.
Meta of prop purposes
When the of prop is used: (1) the MDX content appears in the sidebar inside the component's story list, named according to docs.defaultName (which defaults to 'Docs') in main.js or overridden with the name prop; (2) the component and its stories are attached to the MDX file, allowing other doc blocks to be used in 'attached' mode.
Attached vs unattached docs entries
An 'attached' docs entry is an MDX file associated with a stories file via Meta's of prop; it displays next to the stories list under the component in the sidebar. An 'unattached' docs entry is not associated with a stories file and can be displayed anywhere in the sidebar via Meta's title prop.
Meta block example with of prop
Example: import { Meta } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; <Meta of={ButtonStories} />