Storybook Addon Knobs
Storybook Addon Knobs allow you to edit React props dynamically using the Storybook UI. You can also use Knobs as a dynamic variable inside stories in Storybook.
This is how Knobs look 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.
npm install @storybook/addon-knobs --save-dev
Then, configure it as an addon by adding it to your addons.js
file (located in the Storybook config directory).
;
Now, write your stories with knobs.
With React
;; const stories = ; // Add the `withKnobs` decorator to add knobs support to your stories.// You can also configure `withKnobs` as a global decorator.stories; // Knobs for React propsstories; // Knobs as dynamic variables.stories;
With Angular
;; ; const stories = ; // "withKnobs" decorator should be applied before the stories using knobsstories; // Knobs for Angular propsstories;
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.
// Knob assigned a groupId.stories;
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.
;
Just like that, you can import any other following Knobs:
text
Allows you to get some text from the user.
; const label = 'Your Name';const defaultValue = 'Arunoda Susiripala';const groupId = 'GROUP-ID1'; const value = ;
boolean
Allows you to get a boolean value from the user.
; const label = 'Agree?';const defaultValue = false;const groupId = 'GROUP-ID1'; const value = ;
number
Allows you to get a number from the user.
; const label = 'Age';const defaultValue = 78;const groupId = 'GROUP-ID1'; const value = ;
For use with groupId
, pass the default options
as the third argument
const value = number(label, defaultValue, {}, groupId);
number bound by range
Allows you to get a number from the user using a range slider.
; const label = 'Temperature';const defaultValue = 73;const options = range: true min: 60 max: 90 step: 1;const groupId = 'GROUP-ID1'; const value = ;
color
Allows you to get a colour from the user.
; const label = 'Color';const defaultValue = '#ff00ff';const groupId = 'GROUP-ID1'; const value = ;
object
Allows you to get a JSON object or array from the user.
; const label = 'Styles';const defaultValue = backgroundColor: 'red';const groupId = 'GROUP-ID1'; const value = ;
Make sure to enter valid JSON syntax while editing values inside the knob.
array
Allows you to get an array of strings from the user.
; const label = 'Styles';const defaultValue = 'Red';const groupId = 'GROUP-ID1'; const value = ;
While editing values inside the knob, you will need to use a separator. By default it's a comma, but this can be override by passing a separator variable.
;const label = 'Styles';const defaultValue = 'Red';const separator = ':';const value = ;
For use with groupId
, pass the default separator
as the third argument
const value = array(label, defaultValue, ',', groupId);
select
Allows you to get a value from a select box from the user.
; 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 = ;
You can also provide options as an array like this:
['red', 'blue', 'yellow']
files
Allows you to get a value from a file input from the user.
; const label = 'Images';const defaultValue = ; const value = ;
Multiple files can be selected, and will be returned as an array of Data URLs
date
Allow you to get date (and time) from the user.
; const label = 'Event Date';const defaultValue = 'Jan 20 2017';const groupId = 'GROUP-ID1'; const value = ;
Note: the default value must not change - e.g., do not do
date('Label', new Date())
ordate('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:
{ const stringTimestamp = return stringTimestamp}
button
Allows you to include a button and associated handler.
; const label = 'Do Something';const handler = ;const groupId = 'GROUP-ID1'; ;
withKnobs options
withKnobs also accepts two optional options as story parameters. Usage:
;; const stories = ; storiesstories;
Typescript
If you are using typescript, make sure you have the type definitions installed for the following libs:
- node
- react
You can install them using npm install -save @types/node @types/react
, assuming you are using Typescript >2.0.