> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Storybook helpers

> Present component previews and variant catalogs with twenty-ui/testing.

`twenty-ui/testing` exposes Storybook decorators and preview layout helpers. Configure styles and a [ThemeProvider](/ui/theming) in your Storybook preview before rendering themed components.

## Story roles

Start each component guide with a `Display` story showing one representative, usable example. Follow it with Usage code that reproduces the preview using public imports. Compound components demonstrate their parts together. Providers and accessibility helpers demonstrate their effect in context.

Add a `Catalog` when a labeled comparison helps readers choose between visual options. Group variants, sizes, colors, and states separately; use a matrix only when comparing two dimensions together is useful. A simple component can use one alternative example. Dialogs, menus, and other interactive components usually need focused examples for each workflow.

Preserve comprehensive screenshot coverage in separate `VisualRegression` stories, including dark themes and variant matrices. Tag those stories with `!autodocs` and keep them out of the component guides.

Name other stories after what they demonstrate, such as `Controlled`, `WithValidation`, or `MultipleSelection`. Keep interaction checks in separate stories with `play` functions. The display and other documentation previews remain usable by the reader without automated actions.

## ComponentDecorator

`ComponentDecorator` wraps a story in `ComponentStorybookLayout`. Set `parameters.container.width` and `parameters.container.height` in pixels. It also reads the story's `inverted` and `accent` args to choose an optional background.

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { ComponentDecorator } from 'twenty-ui/testing';

const meta = {
  component: Button,
  decorators: [ComponentDecorator],
  parameters: { container: { width: 240, height: 100 } },
};

export default meta;

export const Display = { args: { children: 'Save changes' } };
```

## GroupedCatalog

`GroupedCatalog` gives curated catalogs a shared layout for headings, wrapping rows, and spacing. Each group has a `label` and an `examples` array. Every example needs a unique `label` within its group; it can carry any other data used by `renderExample`.

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';
import { GroupedCatalog } from 'twenty-ui/testing';

const groups = [
  {
    label: 'Variants',
    examples: [
      { label: 'Solid', variant: 'solid' as const },
      { label: 'Outline', variant: 'outline' as const },
    ],
  },
];

export const ButtonCatalog = () => (
  <GroupedCatalog
    groups={groups}
    renderExample={({ label, variant }) => (
      <>
        <Text>{label}</Text>
        <Button variant={variant}>Save changes</Button>
      </>
    )}
  />
);
```

<ParamField body="groups" type="{ label: string; examples: CatalogExample[]; }[]" required>
  Labeled groups of examples. Each example has a unique label within its group and can include additional data for the renderer.
</ParamField>

<ParamField body="renderExample" type="(example: CatalogExample) => ReactNode" required>
  Renders one example, including its visible label or accessible name. The layout supplies the surrounding cell and spacing.
</ParamField>

## CatalogDecorator

`CatalogDecorator` renders combinations of up to four dimensions from `parameters.catalog.dimensions`. Each dimension has a `name`, `values`, a `props(value)` mapper, and an optional `labels(value)` formatter. The mapper returns the props for that cell. `parameters.catalog.options.elementContainer` accepts `width`, `style`, and `className`.

```tsx theme={null}
import { Button, type ButtonVariant } from 'twenty-ui/primitives/input';
import { CatalogDecorator } from 'twenty-ui/testing';

const meta = { component: Button };
export default meta;

export const Catalog = {
  args: { children: 'Save changes' },
  decorators: [CatalogDecorator],
  parameters: {
    catalog: {
      dimensions: [
        {
          name: 'variant',
          values: ['outline', 'solid', 'ghost'],
          props: (variant: ButtonVariant) => ({ variant }),
        },
      ],
    },
  },
};
```

## ComponentStorybookLayout

Use the layout directly when composing a preview outside a decorator. It accepts one child element.

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { ComponentStorybookLayout } from 'twenty-ui/testing';

export const ButtonPreview = () => (
  <ComponentStorybookLayout width={240} height={100}>
    <Button>Save changes</Button>
  </ComponentStorybookLayout>
);
```

<ParamField body="backgroundColor" type="string">
  Background color override.
</ParamField>

<ParamField body="children" type="Element" required>
  The component preview element.
</ParamField>

<ParamField body="height" type="number">
  Container height in pixels. Defaults to fit-content.
</ParamField>

<ParamField body="width" type="number">
  Container width in pixels. When omitted, the container has a 300px minimum width.
</ParamField>

## Documentation previews

Stories embedded in the documentation must be presentational and have no `play` function. Keep interaction tests in separate stories. Share explicit `args`, `render`, `decorators`, and `parameters` when needed, rather than spreading an interaction story into a preview. The documentation embed check rejects stories marked with Storybook's `play-fn` tag, including inherited play functions.

Each component guide's first embed must reference a story exported as `Display`. Give every embed a descriptive title for its iframe and enough height to show the example. The shared preview supplies light and dark tabs and a link to Storybook, where readers can use controls to explore props.

Run `npx nx check:ui-stories twenty-docs` to check the required display, preview titles, references, and presentation rules. Run `npx nx check:ui twenty-docs` to validate the generated API references and typecheck copyable examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.