The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: Storybook helpers
description: Present component previews and variant catalogs with twenty-ui/testing.
---
import { PageBanner } from "/snippets/page-banner.mdx"
import ComponentStorybookLayoutReference from '/snippets/ui/generated/testing/component-storybook-layout.mdx';
import GroupedCatalogReference from '/snippets/ui/generated/testing/grouped-catalog.mdx';
## Overview
`twenty-ui/testing` exposes Storybook decorators, preview layout helpers, and media-query overrides. 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
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
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>
</>
)}
/>
);
```
<GroupedCatalogReference />
## 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
import { Button, type ButtonVariant } from 'twenty-ui/primitives/input';
import { CatalogDecorator } from 'twenty-ui/testing';
const meta = { component: Button };
export default meta;
export const VisualRegression = {
tags: ['!autodocs'],
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
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>
);
```
<ComponentStorybookLayoutReference />
## Media query overrides
Use `overrideMediaQueryMatches` in a story's `beforeEach` to force responsive hook results. Return its cleanup function to restore `window.matchMedia` after the story:
```tsx
import { Button } from 'twenty-ui/primitives/input';
import { overrideMediaQueryMatches } from 'twenty-ui/testing';
import { MOBILE_MEDIA_QUERY, useIsMobile } from 'twenty-ui/utilities';
const ResponsiveAction = () => {
const isMobile = useIsMobile();
return <Button fullWidth={isMobile}>Save changes</Button>;
};
const meta = { component: ResponsiveAction };
export default meta;
export const Mobile = {
beforeEach: () => overrideMediaQueryMatches({ [MOBILE_MEDIA_QUERY]: true }),
};
```
Queries omitted from the override retain their native behavior. Override `TOUCH_DEVICE_MEDIA_QUERY` separately when an example depends on touch input. These overrides control `matchMedia` results; use a Storybook viewport to change CSS media queries and the preview width.
## 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.
<PageBanner illustration="card-page-testing" />