Storybook-Animate

Storybook is great for designing indivdual states of your application's components. But your users don't see your app as individual states, but a series of states that flow together over time. If storybook lets you design the frames, Storybook-Animate lets you create the flipbook!

Simplicity Breeds Creativity

Where you used to provide a story of a single component with props:

storiesOf('Thermometer', module)
  .add('Healthy Temperature', () => (
    <Thermometer scale="F" temp={98.6}>
  ))

You can animate the component with a propStream

storiesOf('Thermometer', module)
  .add('Healthy Temperature', () => (
    <Animate
      component={Thermometer}
      propStream={climbingTemp}
    />
  ))

And here is the beautiful result:

Try clicking on the animation to restart it, or using <Animate loop={true} ... /> to just sit back and admire your animation :)

Dive into Streams

A propStream is an RxJS Observable, created any way you like. But to ease you in, Storybook-Animate includes some helpers to supplement those provided by Polyrhythm:

const climbingTemp = sequenceOf(
  after(0.0, { temp: 86 }),
  after(1000, { temp: 92 }),
  after(1000, { temp: 96 }),
  after(1000, { temp: 99 }),
  after(1000, { temp: 100.5 }),
  after(1000, { temp: 102.2 })
).combineWith({scale: "F"})

Storybook Your API calls, Loading States, API Errors

Sometimes your users see loading states for a lot longer than you are able to during development—why not have stories for those loading states too? Feel their pain, and design to improve upon it right there in your UX design tool.

Like this example from a recent Storybook:

import { searchApi } from './anotherFile'
 
function AutoComplete() {
  const [results, setResults] = useState([])
  return (
    <input onChange={(e) => {
      searchApi(e.target.text)
        .then(results => setResults(results))
    }/>
    { /* render results */ }
  )
}

import {searchApi} from './anotherFile'
function AutoComplete({ searchFunction = searchApi }) {
  ...
}

const slowSearch = term => after(3000, [
  {text: 'Abacus', value: 1},
  {text: 'AbbA', value: 2}
])).toPromise()

storiesOf('Autocomplete', module)
  .add('Regular Loading', () => (
    <AutoComplete/>
  ))
  .add('Slow Loading', () => (
    <AutoComplete searchFunction={slowSearch} />
  ))

Want to use this with the Knobs addon?

If you have a story that is driven by an Observable, such as one using <Animate> you may wish to use knobs to change that Observable's values, by incorporating the knob's value into the Observable's values.

Or, you may want to use a knob to produce all the values of that Observable. Either way is possible.

  <Animate
    component={Thermometer}
    propStream={climbingTemp}
  />

  <Animate
    component={Thermometer}
    propStream={climbingTemp.pipe(
      map(({ temp }) => ({
        temp,
        scale: select("Scale", { C: "C", F: "F" }, "F")
      }))
    )}
  />

<WithObservableKnob
  knob={[number, "Temp", 98]}
  render={knobTemps => (
    <Animate
      component={Thermometer}
      propStream={knobTemps.pipe(
        map(v => ({ temp: v, scale: "F" }))
      )}
    />
  )}
/>

The Sky's The Limit!

You can combine Storybook-Animate with other means of animations. CSS animations, React Transition Groups internal to your components - you are only limited by what you can come up with!

Got ideas that we haven't thought of? Search for an issue or open one if you don't see it.

Examples

The Thermometer example is in the stories/ folder of this project. Feel free to post a link to what you've built with it too, we can include it here!