Fumadocs

Story

Display components with controls.

Callout

string
string

Introduction

You can use Fumadocs Story to display & document components. It is a simple, docs-focused alternative of Storybook, it is mainly designed for component libraries.

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

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.

When to use it over Storybook?

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

Installation

Follow the installation guide according to your setup:

Headless

Replace the UI of stories, or build your own on the headless layer.

Next.js

Configure Fumadocs Story on Next.js.

Vite

Configure Fumadocs Story for Vite-based frameworks.

Configurations

Variants

You can provide multiple variants of the component with args:

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

Controls are generated from the component props, you can specify the control nodes instead:

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

export const story = defineStory({
  Component: GraphView,
  args: {
    controls: {
      node: {
        type: 'object',
        properties: [],
      },
    },
  },
});

frame

Components filling the viewport, like layouts, can be rendered in an iframe. The story panel scales the frame down to fit, with a button to open it in fullscreen.

components/my-layout.story.tsx
import { defineStory } from '@/lib/story';
import { MyLayout } from './my-layout.lazy';
import { Window } from './window';

export const story = defineStory({
  Component: MyLayout,
  frame: {
    src: '/story/my-layout',
    // viewport size, optional
    width: 1280,
    height: 800,
    // wraps the frame, e.g. in a window, optional
    Container: Window,
  },
});

Create a page at src to render the component, it receives the arguments from the story panel:

app/story/my-layout/page.tsx
import { story } from '@/components/my-layout.story';

export default function Page() {
  return <story.Frame />;
}

Pages with the story would load the component too, pass a lazy one (e.g. next/dynamic or React.lazy) so only the frame loads it:

components/my-layout.lazy.tsx
'use client';
import dynamic from 'next/dynamic';

export const MyLayout = dynamic(() => import('./my-layout').then((mod) => mod.MyLayout));

Good to know

  • The page must be on the same origin as your docs.
  • Arguments are sent with postMessage(), they must be serializable (no functions or JSX).
  • Container must be a client component.

Internationalization

Assuming you have configured Internationalization at UI level:

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())
  .extend(storyTranslations())
  .add({
    cn: {
      displayName: 'Chinese',
      'Add Item(story arguments form)': '新增項目',
    },
  });

See Translations for more details.

How is this guide?

Last updated on

On this page

IntroductionInstallationConfigurationsVariantscontrolsframeInternationalization
Sponsors
General TranslationGeneral TranslationFerry HealthFerry Healthassistant-uiassistant-uiInkeepInkeep