---
title: Story
description: Display components with controls.
---

import { story } from './client.story';

<story.WithControl />

## Introduction

You can use Fumadocs Story to display & document components.
It is a simple, docs-focused alternative of [Storybook](https://storybook.js.org), it is mainly designed for component libraries.

If you are new to the concept of Story, this is a short explanation from **Storybook** docs:

<blockquote>
  A story captures the rendered state of a UI component. It's an object with annotations that
  describe the component's behavior and appearance given a set of arguments.
</blockquote>

<Callout title="When to use it over Storybook?">

Fumadocs Story is not a replacement for Storybook, we still recommend Storybook for proper UI testing.

</Callout>

## Installation

Follow the installation guide according to your setup:

<DocsCategory />

## Configurations

### Variants

You can provide multiple variants of the component with `args`:

```ts
import { defineStory } from '@/lib/story';
import { Callout } from '@/components/callout';

export const story = defineStory({
  Component: Callout,
  args: [
    {
      variant: 'Default',
      initial: {
        title: 'This is a Callout',
      },
    },
    {
      variant: 'Warning',
      initial: {
        title: 'This is a Callout',
      },
      // fixed values for props
      fixed: {
        type: 'warning',
      },
    },
  ],
});
```

### `controls`

You can further customize on how the controls are generated:

```tsx
import { defineStory } from '@/lib/story';
import { GraphView } from '@/components/graph-view';

export const story = defineStory({
  Component: GraphView,
  args: {
    // specify the control nodes
    controls: {
      node: {
        type: 'object',
        properties: [],
      },
    },

    // or customize the generated controls
    controls: {
      transform: (node) => node,
    },
  },
});
```

### Internationalization

Assuming you have configured [Internationalization](/docs/internationalization) at UI level:

```tsx title="layout.shared.tsx"
import { defineI18n } from 'fumadocs-core/i18n';
import { uiTranslations } from 'fumadocs-ui/i18n';
import { storyTranslations } from '@fumadocs/story/i18n';

const i18n = defineI18n({
  languages: ['en', 'cn'],
  defaultLanguage: 'en',
});

export const translations = i18n
  .translations()
  .extend(uiTranslations())
  // [!code ++]
  .extend(storyTranslations())
  .add({
    cn: {
      displayName: 'Chinese',
      // [!code ++]
      'New Item(story arguments form)': '新增項目',
    },
  });
```

See [Translations](/docs/ui/translations) for more details.
