A next-generation tool to create blazing-fast documentation sites
API
created:7/29/2020
,
updated:11/6/2020

Overview

Story is a (relatively) small code example that demonstrates a specific component. You can write stories in mdx or esm format.

For MDX stories, the properties are asigned to the <Story /> component:

import { Story } from '@component-controls/blocks';
<Story name="overview" description="Story description." controls={{ name: 'some text' }}>
{({ name }) => <button>{name}</button>}
</Story>

For ESM stories, the properties can either be assigned to a story namespace:

export const overview = ({ name }) => <button>{name}</button>;
overview.story = {
description: 'Story description.',
controls: {
name: 'some text'
}
}

or directly to the exported function:

export const overview = ({ name }) => <button>{name}</button>;
overview.description = 'Story description.';
overview.controls = {
name: 'some text'
}

Properties

name or storyName

type: string

Name of the story. In ESM stories, the name is automatically created from the name of the exported function. However, you can also override the created name.

MDX

---
title: Library/Components/Spinner
---
import { Story } from '@component-controls/blocks';
<Story name="overview">
<button>click me</button>
</Story>

ESM

import React from 'react';
export default {
title: 'Library/Components/Button',
};
export const overview = () => <button>click me</button>;
overview.storyName = 'custom story name';
//also valid:
overview.story = {
name: 'custom story name',
}
story namestory name

description

type: string

Story extended description, can use markdown.

MDX

---
title: Library/Components/Spinner
---
import { Story } from '@component-controls/blocks';
<Story name="overview" description="story **nice** description">
<button>click me</button>
</Story>

ESM

import React from 'react';
export default {
title: 'Library/Components/Button',
};
export const overview = () => <button>click me</button>;
overview.description = 'story **nice** description'
story descriptionstory description

source

type: string

Story source code is extracted automatically by the AST instrumenting loaders, but can also be overridden manually.

MDX

---
title: Library/Components/Spinner
---
import { Story } from '@component-controls/blocks';
<Playground>
<Story name="overview" source={`
() => <div>custom source code</div>;
`}>
<button>click me</button>
</Story>
</Playground>

ESM

import React from 'react';
export default {
title: 'Library/Components/Button',
};
export const overview = () => <button>click me</button>;
overview.source = `
() => <div>custom source code</div>;
`
story sourcestory source

subtitle

type: string

Optional story subtitle property will be displayed at the top of a documentation page

MDX

---
title: Library/Components/Spinner
---
import { Story } from '@component-controls/blocks';
<Story name="overview" subtitle="story subtitle">
<button>click me</button>
</Story>

ESM

import React from 'react';
export default {
title: 'Library/Components/Button',
};
export const overview = () => <button>click me</button>;
overview.subtitle = 'story subtitle';
story subtitlestory subtitle

component

type: string | object

The component associated with the story.

MDX

---
title: Library/Components/Spinner
---
import { Button } from '../components/Button';
import { Story, PropsTable, ComponentSource } from '@component-controls/blocks';
<Story name="overview" component={Button}>
<Button>click me</Button>
</Story>
## Component source
<ComponentSource of="." />
## Component Props
<PropsTable of="." />

ESM

import React from 'react';
import { Button } from '../components/Button';
export default {
title: 'Library/Components/Button',
};
export const overview = () => <Button>click me</Button>;
overview.component = Button;
story componentstory component

subcomponents

type: `string[] | object[]

Multiple components option.

MDX

---
title: Library/Components/Spinner
---
import { Button } from '../components/Button';
import { Spinner } from '../components/Spinner';
import { Story, PropsTable, ComponentSource } from '@component-controls/blocks';
<Story name="overview" component={Button} subcomponents={{ Spinner }}>
<Button>click me</Button>
</Story>
## Component source
<ComponentSource of="." />
## Component Props
<PropsTable of="." />

ESM

import React from 'react';
import { Button } from '../components/Button';
import { Spinner } from '../components/Spinner';
export default {
title: 'Library/Components/Button',
};
export const overview = () => <Button>click me</Button>;
overview.story = {
component: Button,
subcomponents: { Spinner },
};
story subcomponentsstory subcomponents

controls

type: ComponentControls

An object of key/value pairs specifying the controls for the story.

MDX

---
title: Library/Components/Spinner
---
import { Playground, Story, PropsTable } from '@component-controls/blocks';
<Playground>
<Story name="text-control" controls={{ text: 'some text' }}>
{({ text }) => (
<div>{text}</div>
)}
</Story>
</Playground>
<PropsTable name="text-control" />

ESM

import React from 'react';
export default {
title: 'Library/Components/Button',
};
export const textControls = ({ text }) => <div>{text}</div>;
textControls.controls: { text: 'some text' },

Introduction to controls

story controlsstory controls

smartControls

type SmartControls

"smart" controls options

MDX

---
title: Library/Components/Spinner
---
import { Playground, Story, PropsTable } from '@component-controls/blocks';
import { Button } from '../components/Button';
<Playground>
<Story name="text-control" component={Button} smartControls={{ include: ['color', 'backgroundColor'] }}>
{props => <Button {...props} />}
</Story>
</Playground>
<PropsTable name="text-control" />

ESM

import React from 'react';
import { Button } from '../components/Button';
export default {
title: 'Library/Components/Button',
};
export const textControls = props => <Button {...props} />;
textControls.story = {
component: Button,
smartControls: { include: ['color', 'backgroundColor'] },
}
story smart controlsstory smartControls

decorators

type StoryRenderFn[]

An array of wrapper functions (decorators) that will be called when rendering the story.

MDX

---
title: Library/Components/Spinner
---
import { Playground, Story, PropsTable } from '@component-controls/blocks';
import { Button } from '../components/Button';
<Story name="overview" decorators={[
(controls, context) => {
const { renderFn } = context;
return (
<div style={{ background: 'lightpink' }}>
{renderFn(controls, context)}
</div>
);
},
]}
>
{() => <div>decorator test</div>}
</Story>

ESM

import React from 'react';
export default {
title: 'Library/Components/Button',
};
export const overview = () => <div>decorator test</div>;
overview.decorators = [
(controls, context) => {
const { renderFn } = context;
return (
<div style={{ background: 'lightpink' }}>
{renderFn(controls, context)}
</div>
);
},
];
story decoratorsstory decorators

dynamic

type boolean

If this flag is set to true, the story is a function creating dynamic stories at run-time

ESM

import React from 'react';
import { theme } from '@component-controls/components';
export default {
title: 'Library/Components/Button',
};
export const buttonColors = () => {
return Object.keys(theme.colors)
.filter(color => typeof theme.colors[color] === 'string')
.map(color => {
return {
name: color,
source: `<Button sx={{ bg: '${color}'}}>Color ${color}: ${theme.colors[color]}</Button>`,
renderFn: () => (
<Button
sx={{ bg: color }}
>{`Color ${color}: ${theme.colors[color]}`}</Button>
),
};
});
};
buttonColors.dynamic = true;