Docs
Storybook Docs

Description

Watch a video tutorial

The Description block displays the description for a component, story, or meta, obtained from their respective JSDoc comments.

Screenshot of Description block

{/* ButtonDocs.mdx */}
 
import { Meta, Description } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
<Description of={ButtonStories.Primary} />

Description

import { Description } from '@storybook/blocks';

Description is configured with the following props:

of

Type: Story export or CSF file exports

Specifies where to pull the description from. It can either point to a story or a meta, depending on which description you want to show.

Descriptions are pulled from the JSDoc comments or parameters, and they are rendered as markdown. See Writing descriptions for more details.

Writing descriptions

There are multiple places to write the description of a component/story, depending on what you want to achieve. Descriptions can be written at the story level to describe each story of a component, or they can be written at the meta or component level to describe the component in general.

Descriptions can be written as JSDoc comments above stories, meta, or components. Alternatively they can also be specified in parameters. To describe a story via parameters instead of comments, add it to parameters.docs.description.story; to describe meta/component, add it to parameters.docs.description.component.

We recommend using JSDoc comments for descriptions, and only use the parameters.docs.description.X properties in situations where comments are not possible to write for some reason, 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 they are more discoverable for other developers that are exploring the story/component sources.

When documenting a story, reference a story export in the of prop (see below) and the Description block will look for descriptions in the following order:

  1. parameters.docs.description.story in the story
  2. JSDoc comments above the story

When documenting a component, reference a meta export in the of prop (see below) and the Description block will look for descriptions in the following order:

  1. parameters.docs.description.component in the meta
  2. JSDoc comments above the meta
  3. JSDoc comments above the component

This flow gives you powerful ways to override the description for each scenario. Take the following example:

// Button.jsx
 
/**
 * # The Button component
 * Shows a button
 */
export const Button = () => <button>Click me</button>;
Button.stories.ts|tsx
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
/**
 * # Button stories
 * These stories showcase the button
 */
const meta: Meta<typeof Button> = {
  component: Button
  parameters: {
    docs: {
      description: {
        component: 'Another description, overriding the comments'
      },
    },
  },
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
/**
 * # Primary Button
 * This is the primary button
 */
export const Primary: Story = {
  parameters: {
    docs: {
      description: {
        story: 'Another description on the story, overriding the comments'
      },
    },
  },
};
{/* ButtonDocs.mdx */}
 
import { Meta, Description } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
{/* 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 */}
<Description of={ButtonStories} />
 
{/* Shows the description for the Primary export */}
<Description of={ButtonStories.Primary} />