Storybook Addon Knobs

Storybook Addon Knobs allow you to edit props dynamically using the Storybook UI.
You can also use Knobs as a dynamic variable inside stories in Storybook.

Framework Support.

This is what Knobs looks like:


> Checkout the above Live Storybook or watch this video.

Getting Started

First of all, you need to install Knobs into your project as a dev dependency.

``sh
yarn add @storybook/addon-knobs --dev
`

within .storybook/main.js:

`js
module.exports = {
addons: ['@storybook/addon-knobs'],
};
`

Now, write your stories with Knobs.

$3

`js
import React from 'react';
import { withKnobs, text, boolean, number } from '@storybook/addon-knobs';

export default {
title: 'Storybook Knobs',
decorators: [withKnobs],
};
// Add the withKnobs decorator to add knobs support to your stories.
// You can also configure withKnobs as a global decorator.

// Knobs for React props
export const withAButton = () => (
{text('Label', 'Hello Storybook')}
);

// Knobs as dynamic variables.
export const asDynamicVariables = () => {
const name = text('Name', 'James');
const age = number('Age', 35);
const content = I am ${name} and I'm ${age} years old.;

return

;
};
`

$3

MyButton.story.js:

`js
import { storiesOf } from '@storybook/vue';
import { withKnobs, text, boolean } from '@storybook/addon-knobs';

import MyButton from './MyButton.vue';

export default {
title: 'Storybook Knobs',
decorators: [withKnobs],
};

// Assign props to the story's component, calling
// knob methods within the default property of each prop,
// then pass the story's prop data to the component’s prop in
// the template with v-bind: or by placing the prop within
// the component’s slot.
export const exampleWithKnobs = () => ({
components: { MyButton },
props: {
isDisabled: {
default: boolean('Disabled', false),
},
text: {
default: text('Text', 'Hello Storybook'),
},
},
template: {{ text }},
});
`

MyButton.vue:

`vue



`

$3

`js
import { storiesOf } from '@storybook/angular';
import { boolean, number, text, withKnobs } from '@storybook/addon-knobs';

import { Button } from '@storybook/angular/demo';

export default {
title: 'Storybook Knobs',
decorators: [withKnobs],
};

export const withKnobs = () => ({
component: Button,
props: {
text: text('text', 'Hello Storybook'), // The first param of the knob function has to be exactly the same as the component input.
},
});
`

$3

`js
import { withKnobs, text, boolean } from '@storybook/addon-knobs';
import { hbs } from 'ember-cli-htmlbars';

export default {
title: 'StoryBook with Knobs',
decorators: [withKnobs],
};

export const button = () => ({
template: hbs
{{label}}
,
context: {
label: text('label', 'Hello Storybook'),
disabled: boolean('disabled', false),
},
});
`

Categorization

Categorize your Knobs by assigning them a groupId. When a groupId exists, tabs will appear in the Knobs storybook panel to filter between the groups. Knobs without a groupId are automatically categorized into the ALL group.

`js
export const inGroups = () => {
const personalGroupId = 'personal info';
const generalGroupId = 'general info';

const name = text('Name', 'James', personalGroupId);
const age = number('Age', 35, { min: 0, max: 99 }, personalGroupId);
const message = text('Hello!', 35, generalGroupId);
const content =
I am ${name} and I'm ${age} years old.
${message}
;

return

;
};
`

You can see your Knobs in a Storybook panel as shown below.


Available Knobs

These are the Knobs available for you to use. You can import these Knobs from the @storybook/addon-knobs module.
Here's how to import the text Knob.

`js
import { text } from '@storybook/addon-knobs';
`

Just like that, you can import any other following Knobs:

$3

Allows you to get some text from the user.

`js
import { text } from '@storybook/addon-knobs';

const label = 'Your Name';
const defaultValue = 'James';
const groupId = 'GROUP-ID1';

const value = text(label, defaultValue, groupId);
`

$3

Allows you to get a boolean value from the user.

`js
import { boolean } from '@storybook/addon-knobs';

const label = 'Agree?';
const defaultValue = false;
const groupId = 'GROUP-ID1';

const value = boolean(label, defaultValue, groupId);
`

$3

Allows you to get a number from the user.

`js
import { number } from '@storybook/addon-knobs';

const label = 'Age';
const defaultValue = 78;
const groupId = 'GROUP-ID1';

const value = number(label, defaultValue);
`

For use with groupId, pass the default options as the third argument.

`js
const value = number(label, defaultValue, {}, groupId);
`

$3

Allows you to get a number from the user using a range slider.

`js
import { number } from '@storybook/addon-knobs';

const label = 'Temperature';
const defaultValue = 73;
const options = {
range: true,
min: 60,
max: 90,
step: 1,
};
const groupId = 'GROUP-ID1';

const value = number(label, defaultValue, options, groupId);
`

$3

Allows you to get a colour from the user.

`js
import { color } from '@storybook/addon-knobs';

const label = 'Color';
const defaultValue = '#ff00ff';
const groupId = 'GROUP-ID1';

const value = color(label, defaultValue, groupId);
`

$3

Allows you to get a JSON object or array from the user.

`js
import { object } from '@storybook/addon-knobs';

const label = 'Styles';
const defaultValue = {
backgroundColor: 'red',
};
const groupId = 'GROUP-ID1';

const value = object(label, defaultValue, groupId);
`

> Make sure to enter valid JSON syntax while editing values inside the knob.

$3

Allows you to get an array of strings from the user.

`js
import { array } from '@storybook/addon-knobs';

const label = 'Styles';
const defaultValue = ['Red'];
const groupId = 'GROUP-ID1';

const value = array(label, defaultValue);
`

> While editing values inside the knob, you will need to use a separator.
> By default it is a comma, but this can be overridden by passing a separator variable.
>
> `js
> import { array } from '@storybook/addon-knobs';
>
> const label = 'Styles';
> const defaultValue = ['Red'];
> const separator = ':';
> const value = array(label, defaultValue, separator);
> `

For use with groupId, pass the default separator as the third argument.

`js
const value = array(label, defaultValue, ',', groupId);
`

$3

It allows you to get a value from a select box from the user.

`js
import { select } from '@storybook/addon-knobs';

const label = 'Colors';
const options = {
Red: 'red',
Blue: 'blue',
Yellow: 'yellow',
Rainbow: ['red', 'orange', 'etc'],
None: null,
};
const defaultValue = 'red';
const groupId = 'GROUP-ID1';

const value = select(label, options, defaultValue, groupId);
`

Options can also be an array:

`js
import { select } from '@storybook/addon-knobs';
const label = 'Cats';
const options = ['linus', 'eleanor', 'lover'];
const defaultValue = 'eleanor';
const groupId = 'GROUP-ID2';
const value = select(label, options, defaultValue, groupId);
`

Options can also be an array OF objects:

`js
const label = 'Dogs';
const arrayOfObjects = [
{
label: 'Sparky',
dogParent: 'Matthew',
location: 'Austin',
},
{
label: 'Juniper',
dogParent: 'Joshua',
location: 'Austin',
},
];
const defaultValue = arrayOfObjects[0];
const groupId = 'GROUP-ID3';
const value = select(label, arrayOfObjects, defaultValue, groupId);
`

$3

It allows you to get a value from a list of radio buttons from the user.

`js
import { radios } from '@storybook/addon-knobs';

const label = 'Fruits';
const options = {
Kiwi: 'kiwi',
Guava: 'guava',
Watermelon: 'watermelon',
};
const defaultValue = 'kiwi';
const groupId = 'GROUP-ID1';

const value = radios(label, options, defaultValue, groupId);
`

$3

Configurable UI for selecting a value from a set of options.

`js
import { optionsKnob } from '@storybook/addon-knobs';

const label = 'Fruits';
const valuesObj = {
Kiwi: 'kiwi',
Guava: 'guava',
Watermelon: 'watermelon',
};
const defaultValue = 'kiwi';
const optionsObj = {
display: 'inline-radio',
};
const groupId = 'GROUP-ID1';

const value = optionsKnob(label, valuesObj, defaultValue, optionsObj, groupId);
`

Alternatively you can use this import:
`
import { optionsKnob as options } from '@storybook/addon-knobs';

...

const value = options(label, valuesObj, defaultValue, optionsObj, groupId);
`

> The display property for optionsObj accepts:
>
> - radio
> - inline-radio
> - check
> - inline-check
> - select
> - multi-select

$3

It allows you to get a value from a file input from the user.

`js
import { files } from '@storybook/addon-knobs';

const label = 'Images';
const accept = '.xlsx, .pdf';
const defaultValue = [];
const groupId = 'GROUP-ID1';

const value = files(label, accept, defaultValue, groupId);
`

> You can optionally specify a list of file types which the file input should accept.
> Multiple files can be selected, and will be returned as an array of Data URLs.

$3

Allows you to get date (and time) from the user.

`js
import { date } from '@storybook/addon-knobs';

const label = 'Event Date';
const defaultValue = new Date('Jan 20 2017');
const groupId = 'GROUP-ID1';

const value = date(label, defaultValue, groupId);
`

> Note: the default value must not change - e.g., do not do date('Label', new Date()) or date('Label').

The date knob returns the selected date as stringified Unix timestamp (e.g. "1510913096516").
If your component needs the date in a different form you can wrap the date function:

`js
function myDateKnob(name, defaultValue) {
const stringTimestamp = date(name, defaultValue);
return new Date(stringTimestamp);
}
`

$3

It allows you to include a button and associated handler.

`js
import { button } from '@storybook/addon-knobs';

const label = 'Do Something';
const handler = () => doSomething('foobar');
const groupId = 'GROUP-ID1';

button(label, handler, groupId);
`

Button knobs cause the story to re-render after the handler fires.
You can prevent this by having the handler return false.

$3

withKnobs also accepts two optional options as story parameters.
Usage:

`js
import { withKnobs } from '@storybook/addon-knobs';

export default {
title: 'Storybook Knobs',
decorators: [withKnobs],
};

export const defaultView = () =>