The controls api provides an extensible interface for specifying and using input controls to enter component property values at run-time.
You can also check the list of pre-defined controls that are available for creating interactive examples of your components.
You can use controls in both formats ESM and MDX.
- Attach a controls object to your
example
- Ensure your
example
accepts the same parameters as declared in the controls object.
import { ControlTypes } from '@component-controls/core';export const textControl = ({ text }) => (<div>{props.text}</div>);textControl.controls = {text: { type: ControlTypes.TEXT, value: 'some text'}};
import { ControlTypes } from '@component-controls/core';import { Story, Playground, PropsTable } from '@component-controls/blocks';<Story name="text-control" controls={{ text: { type: ControlTypes.TEXT, value: 'some text'} }}>{props => (<div>{props.text}</div>)}</Story>
The component-controls built-in instrumentation module provides the ability to smartly detect any properties passed to your "stories" and creates the controls table accordingly.
- No properties are passed to the example. In this case, no controls will be used at run-time, since the properties can not be passed to the example:
export const overview = () => <button>no props</button>
Name | Description | Default |
---|
- Some named properties are passed to the example. In this case, only the properties specifically listed will be available at run-time (ie:
backgroundColor
):
export const overview = ({ backgroundColor }) => <button style={{ backgroundColor }}>some props</button>
Name | Description | Default | Controls |
---|---|---|---|
backgroundColor | color | grey |
- All the properties are passed. In this case, all listed controls will be available at run-time:
export const overview = props => <button style={props}>all props</button>
Name | Description | Default | Controls |
---|---|---|---|
backgroundColor | color | grey | |
padding | number | 10 |
All controls can receive the following configuration properties
Full text property description with markdown support. It is used in the Props table.
Name | Description | Default | Controls |
---|---|---|---|
text | a description with markdown support text | some text |
Hide the property editor for this property will only use the value.
Name | Description | Default |
---|
Label to display next to the field editor by default uses the property name itself.
Name | Description | Default | Controls |
---|---|---|---|
Enter some text: | text | some text |
Allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
Name | Description | Default | Controls |
---|---|---|---|
text2 | text | text 2 | |
text1 | text | text 1 |
Visually display the control property as required in the Props table.
Name | Description | Default | Controls |
---|---|---|---|
text | text | some text |
The default value that will be displayed in the Props table and the value that will be reverted to when the user clicks on reset. By default it is set from the value field of the control but you can also assign it manually.
Name | Description | Default | Controls |
---|---|---|---|
text | text | a default value |
data helper information to generate random data will be used in conjunction with faker.js.
data: {name: string; //faker.js name of data generatoroptions: object; // options to be passed to the faker data generator}
export const overview = ({ street }) => street;overview.controls = {street: {type: ControlTypes.TEXT,label: 'Street',value: '30333 Atlantic Ave.',data: { name: 'address.streetAddress' },},};
Name | Description | Default | Controls |
---|---|---|---|
Street | text | 30333 Atlantic Ave. |
export const overview = ({ number }) => number;overview.controls = {number: {type: ControlTypes.NUMBER,label: 'A number',value: 10,data: { name: 'random.number', options: { min: 50, max: 100 } },}}
Name | Description | Default | Controls |
---|---|---|---|
Street | text | 30333 Atlantic Ave. |
The controls module can automatically extract component properties from the components prop info (ie typescript interfaces or react-props). This extraction process is called smart-props
.
The make
smart-props
work, you need to assign a component to your ESM or MDX documents (will aplpy to all stories defined) or to a specific story.You also need to pass some parameters to your stories:
import { Button } from '../components/Button';export default {title: 'Smart Controls',component: Button,};export const smart = props => <Button {...props} />;
---title: Smart Controlscomponent: Button---import { Story, Playground, PropsTable } from '@component-controls/blocks';import { Button } from '../components/Button';<Playground><Story name='smart'>{props => <Button {...props} />}</Story></Playground><PropsTable name="smart" />
Name | Description | Default | Controls |
---|---|---|---|
disabled | boolean | - | |
backgroundColor | color | #fefefe | |
color | color | black | |
type | options | button | |
padding | number | 5 |
You can the behavior or smart-controls using the smartControls
story property
If you assign false to smartControls
, the system will skip creating automatically smart controls for the story.
ESM
import { Button } from '../components/Button';export default {title: 'Smart Controls',};export const smart = props => <Button {...props} />;smart.component = Button;smart.smartControls = false;
MDX
---title: Smart Controls---import { Story, Playground, PropsTable } from '@component-controls/blocks';import { Button } from '../components/Button';<Playground><Story name='smart' component={Button} smartControls={false}>{props => <Button {...props} />}</Story></Playground><PropsTable name="smart" />
You might want to configure only some properties of your components to be editable.
ESM
import { Button } from '../components/Button';export default {title: 'Smart Controls',};export const smart = props => <Button {...props} />;smart.component = Button;smart.smartControls = {include: ['color', 'backgroundColor'],};
MDX
---title: Smart Controls---import { Story, Playground, PropsTable } from '@component-controls/blocks';import { Button } from '../components/Button';<Playground><Story name='smart' component={Button} smartControls={{ include: ['color', 'backgroundColor'] }}>{props => <Button {...props} />}</Story></Playground><PropsTable name="smart" />
Name | Description | Default | Controls |
---|---|---|---|
backgroundColor | color | #fefefe | |
color | color | black |
You might want to prevent some properties of your components to be editable.
ESM
import { Button } from '../components/Button';export default {title: 'Smart Controls',};export const smart = props => <Button {...props} />;smart.component = Button;smart.smartControls = {exclude: ['color', 'backgroundColor'],};
MDX
---title: Smart Controls---import { Story, Playground, PropsTable } from '@component-controls/blocks';import { Button } from '../components/Button';<Playground><Story name='smart' component={Button} smartControls={{ exclude: ['color', 'backgroundColor'] }}>{props => <Button {...props} />}</Story></Playground><PropsTable name="smart" />
Name | Description | Default | Controls |
---|---|---|---|
disabled | boolean | - | |
type | options | button | |
padding | number | 5 |
By assigning a groupId
property you can display the properties grouped in different tabs. This works both when creating controls from scratch, or using smart-controls and just overriding their groupId field.
ESM
import { Button } from '../components/Button';export default {title: 'Smart Controls',};export const smart = props => <Button {...props} />;smart.component = Button;smart.controls = {color: { groupId: 'Colors' },backgroundColor: { groupId: 'Colors' }};
MDX
---title: Smart Controls---import { Story, Playground, PropsTable } from '@component-controls/blocks';import { Button } from '../components/Button';<Playground><Story name='smart'component={Button}controls={{color: { groupId: 'Colors' },backgroundColor: { groupId: 'Colors' }}}>{props => <Button {...props} />}</Story></Playground><PropsTable name="smart" />
Name | Description | Default | Controls | |
---|---|---|---|---|
- (3 properties) | ||||
disabled | boolean | - | ||
type | options | button | ||
padding | number | 5 | ||
Colors (2 properties) |