Does Storybook have an opinion or mechanism for providing state to controlled components?

[dwjohnston]

Introduction

In my current code base, I commonly write stories like this:

export const WayIUsuallyDoIt = () => {
    const [value, setValue] = useState(null as null | string);
    return <>
        <p>
            I often also include a debug panel up here, to show the currently selected value: {value}
        </p>
        <Select availableOptions={values}
            selectedValue={value}
            onChange={setValue}
            labelGenFn={(v) => v.label}
            valueGenFn={(v) => v.id}
            label="My Select" />
    </>
}

That is, I have a controlled component. I want to test the behaviour of this component, allow the viewer to see how it behaves as you select new items.

To do this, I declare state in the storybook component.

What's in the docs?

There is the Actions essential plug in, which can detect click events etc. This appears to be good for detecting standard 'onClick' or 'onSubmit' type payloads, but doesn't appear to have a mechanism for setting some state.

The controls don't appear to have a function type arg, and in anycase, the use case I've got here actually pairs two of the args (onChange and selectedValue) together.

My investigation

I have done a bit of an investigation here.

We can also write a story like this:

function StoryRender(props: Omit<SelectProps<typeof values[number]>, "onChange" | "selectedValue">) {
    const [value, setValue] = useState(null as null | string);

    return <>
        <p>
            I often also include a debug panel up here, to show the currently selected value: {value}
        </p>
        <Select
            {...props}
            selectedValue={value}
            onChange={setValue}
        />
    </>
}

export const NewWayAttempt2: Story = {
    args: {
        availableOptions: values,
        labelGenFn: (v) => v.label,
        valueGenFn: (v) => v.id,
        label: "My Label",
        // Omit onChange, selectedValue, those are handled in render fn. 
    },
    render: (args) => {
        return <StoryRender {...args} />
    }
}

This works absolutely fine.

What I'm wondering here, is am I missing a feature, or does Storybook otherwise have an opinion on how we would demonstrate this behaviour?

[chakAs3]

Hi @dwjohnston sorry we could not answer your interesting question we were busy with the V7 RC.
So my opinion is what you are doing is the right way to do it. i don't think that Storybook should provide a state or even alter the state for your component directly. Normal your component could have his inner/local state and Storybook can only interact through the props which is safe and your component should be inside you app.
Storybook gives a testing mechanism in isolation so it should not break this contract by providing external state or changing it.

So the answer for me is you newWayAttempt2 seems just perfect.

[chakAs3]

The controls don't appear to have a function type arg

yes storybook control can't be function as it will be issue with code injection which is not safe, however args can be functions that return a values type string , number , json , string[] ,number[] ...

[jeremydrichardson]

Would it make sense to treat args as state? I mean essentially args are state, you can edit it directly and it update the component right away.

My use case is for a RadioGroup. If we could use the onChange handler to modify the args then it wouldn't require the addition of state.

I know it works fine adding state but the automated documentation ends up being different than it should be used since you have to add an intermediate component that holds the state.

I'm sure it's not trivial to add something like this but wondering if it even makes sense based on the Storybook paradigm.

[Dron007]

There is the Actions essential plug in, which can detect click events etc. This appears to be good for detecting standard 'onClick' or 'onSubmit' type payloads, but doesn't appear to have a mechanism for setting some state.

You can add custom action if you add onChange handler:

  import { action } from '@storybook/addon-actions'
...
  const onChange = (value) => {
    action('onChange')(value) // or action('onChange: ' + value)()
    setValue(value)
  }

Unfortunately, it is undocumented AFAIK.
There is also a partly-documented (for addons case) useArgs hook, from which you can get setArgs function and call it to modify args. But for it to work properly it might also require adding useEffect. Here is an example but it still works incorrectly for Stories in Docs due to some reason: https://stackblitz.com/edit/github-uixpen-fdysyn?file=.storybook%2Fpreview.js,src%2Fstories%2FInputField.stories.js

I find it is very confusing that we have Controls block which doesn't show current value and editing value there doesn't work. So I tried to make it work but faced with many problems especially for class-based components and the code of stories is cumbersome now. I think that Storybook should provide some callback functions which add two-directional connection between properties like value and onChange. Value in Controls should reflect component's state and when value is updated in Controls, component should get new value as an input.
It is also crucial to have correct sources in Source block. After I added useEffect()there is a source code of the story instead of the clear example of the component usage.

[Dron007]

I think I fixed all the problems and could connect controlled component to Controls. See here: https://stackblitz.com/edit/github-uixpen-p6osgl?file=src%2Fstories%2FInputField.js,src%2Fstories%2FInputField.stories.js

To make code cleaner I added useControlledProps hook which can be reused:

const useControlledProps = (args) => {
  const [, setArgs] = useArgs()
  const [value, setValue] = useState(args.value || null)

  useEffect(() => {
    action('onChange')(args.value)
    setValue(args.value)
  }, [args.value])

  const onChange = (value) => {
    action('onChange')(value)
    setArgs({ value: value })
    setValue(value)
  }

  return ({
    value: value,
    onChange: onChange,
  })
}

and use in component's template:

const Template = {
  render: function Render(args) {
    const { value, onChange } = useControlledProps(args)

    return <>
      <InputField
        {...args}
        value={value}
        onChange={onChange}
      />
      <button onClick={() => {onChange('ddd')}}>set "ddd" value</button>
    </>
  },
}```
For functional components it works good.

[Dron007]

There is a simpler solution since that time which I found in some tutorial. Here it is:

import { useArgs } from '@storybook/preview-api'
// optionally use it if you need to send custom action to the Controls table
import { action } from '@storybook/addon-actions'
import SomeComponent from './Index'

export default {
  component: SomeComponent,
  // without this doSomething will not be added to args object
  // (as it is not matched by argTypesRegex "on*" regEx in preview.js)
  argTypes: {
    doSomething: {
      action: 'closeModal',
    },
  },
}

// If you don't need Template just use Default here
const Template = {
  render: function Component (args) {
    const [, setArgs] = useArgs()

    const onChange = (value) => {
      // to add action in Actions tab calling component's callback function.
      // It should be specified in preview.js parameters in his form (it is by default)
      //   const parameters = {
      //     actions: { argTypesRegex: "^on[A-Z].*" },
      //   }
      // Otherwise, see doSomething
      args.onChange(value)
      // change value in Controls table
      setArgs({ value: value })
    }

    const doSomething = (value) => {
      args.doSomething(value)
      setArgs({ value: value })
    }

    // in rare cases you need to add custom action in Actions tab without
    // calling any component's callback function
    // e.g. you are processing onSubmit of wrapping Form component
    // and want to log it in actions tab too
    const onFormChange = (value) => {
      action('form onFormChange(value)')(value)
    }

    return (
      <Form onSubmit={onFormChange}>
        <SomeComponent
          {...args}
          onChange={onChange}
          doSomething={doSomething}
        />
      </Form>
    )
  },
  args: {
    // if you need general args add them here
  },
}

export const Default = {
  ...Template,
  args: {
    value: null,
    anyProp: 42,
  },
}

I compiled it from my several components and didn't check so some typos may exist. This code covers specific cases you probably don't always need. If you have typical onChange/value pair it is very simple and there is no need in custom hook.

[Dron007]

So it can be as simple as this:

import { useArgs } from '@storybook/preview-api'

import SomeComponent from './Index'

export default {
  component: SomeComponent,
}

export const Default = {
  render: function Component (args) {
    const [, setArgs] = useArgs()

    const onChange = (value) => {
      args.onChange(value)
      setArgs({ value: value })
    }

    return <SomeComponent {...args} onChange={onChange} />
  },
  args: {
    value: null,
  },
}

I hope something like this will be added to the documentation. Almost all my controls are controlled components.

[Trevodorax]

Hey @Dron007, thanks a lot for your contribution to this, I'm using your method and it works great !

I'm just wondering: what purpose does the args.onChange(value) inside the onChange function serve ?
I couldn't figure it out, and therefore removed it from my code and it still works the same.

[Dron007]

@Trevodorax This line is required to inform Storybook about changes, to update value in Controls (table of props) and for controlled components to update them too. Maybe your component is not fully controlled and memorize its value internally ignoring value property or using it only initially.

[devnull69]

This is what I came up with ... and it works. The main difference is using action("onChange")(value) rather than args.onChange(value) because the latter just didn't work for me.

import { useArgs } from "@storybook/preview-api";
import { action } from "@storybook/addon-actions";
import SomeComponent from "../components/somecomponent";

export default {
  title: "SomeComponent",
  component: SomeComponent,
  argTypes: {
    onChange: { action: "onChange" },
  },
};

const Template = (args) => {
  const [, setArgs] = useArgs();

  const onChange = (value) => {
    action("onChange")(value);
    setArgs({ value: value.target.value });     // or just value: value if the source is not a standard event!
  };

  return <AutogrowTextarea {...args} onChange={onChange} />;
};

export const Default = Template.bind({});
Default.args = {
  value: "",
};

[chantastic]

my preference for wrapping controlled components with stateful components (in React) is Decorators.

you could pair this with Actions to spy on the event-handling interfaces. this would allow you to avoid building an ad-hoc logger inside the canvas.

we use play functions to put stories into specific states — using testing-library events.
i (personally) think that it's important to enact state changes thru public interfaces.

[jacobleetodd]

@chantastic can you please elaborate? For example how do the pass the state to the story. The decorator docs mention in a code comment that Story can also be called as a function so I assume this is how it would be done. But unfortunately this isn't working for me - though I assume I'm doing something wrong :)

export default {
  component: Dialog,
  decorators: [
    (Story) => {
      const [isOpen, setIsOpen] = useState<boolean>(false);

      return (
        <>
          {Story({
            children: (
              <>
                <DialogTitle>Here is a title</DialogTitle>
                <DialogContent>
                  <DialogContentText>Here is some content</DialogContentText>
                </DialogContent>
                <DialogActions>
                  <Button id="button" onClick={() => setIsOpen(false)}>
                    Ok!
                  </Button>
                </DialogActions>
              </>
            ),
            open: isOpen,
            onClose: () => setIsOpen(false),
          })}
          <Button id="button" onClick={() => setIsOpen(true)}>
            Click to open the dialog
          </Button>
        </>
      );
    },
  ],
  title: "Feedback / Dialog",
} satisfies Meta<typeof Dialog>;

I get this error in the console:

Warning: Failed prop type: The prop `open` is marked as required in `ForwardRef(Modal2)`, but its value is `undefined`.

Thanks!

[ekeijl]

@jacobleetodd Here's an example using a decorator:

• A decorator gets the story args property in an object as second parameter: (Story, { args }) => { ... }
• Return <Story args={{ ...args, whatever }}> from the decorator function.
• Don't forget to name your file .stories.jsx instead of .stories.js or your bundler might fail on the JSX syntax.

// Button.stories.jsx
import { Button } from "./Button";
import React, { Fragment, useState } from "react";

const DisabledStateDecorator = (Story, { args }) => {
  const [disabled, setDisabled] = useState(true);

  return (
    <Fragment>
      <button onClick={() => setDisabled((isDisabled) => !isDisabled)}>
        Toggle disabled
      </button>
      <Story args={{ ...args, disabled }} />
    </Fragment>
  );
};

export const DisabledButton = {
  args: { },
  decorators: [DisabledStateDecorator],
};

Example here (see Button.stories.jsx -> Disabled): https://codesandbox.io/p/devbox/fkgg9y

[plaa]

This decorator works like a charm and neatly keeps the logic separate without having to work with render functions and templates. By far the best answer. 👏 💎

In my case for a dropdown selector the decorator is as simple as:

  decorators: [
    (Story, { args }) => {
      const [selectedOption, setSelectedOption] = useState(args.selectedOption);
      return <Story args={{ ...args, selectedOption, onChange: setSelectedOption }} />;
    },
  ],

[Dron007]

I faced the issue discussed here with caret moving to the end of field on editing (due to async update in useArgs) and I had to restore my old variant (see there or here). It was the only way to keep bidirectional connection between Controls and component, correctly display logs in Actions tab and prevent moving caret to the end.

By the way variant in documentation doesn't work correctly too moving caret to the end.

[Dron007]

Starting from v9 or v10 (I was upgrading from v8) new problem appeared and my previous hook gives this error:

Storybook preview hooks can only be called inside decorators and story functions.

on any edit.

Here is my hook with imports:

import { useState, useEffect } from 'react'
import { useArgs } from 'storybook/preview-api'

/**
 *  This hook connects any controlled component to Storybook's Controls block
 *  providing bi-directional updates of value and args.value when onChange is
 *  called or when args.value is changed in Controls block.
 *
 *  Examples:
 *
 *  import { useControlledProps } from '/.storybook/hooks' // eslint-disable-line import/no-absolute-path
 *
 *  const Template = {
 *    render: function Render (args) {
 *      const [ value, onChange ] = useControlledProps()
 *      // value is needed here to prevent moving caret to the end in text inputs
 *      return <>
 *        <InputField {...args} onChange={onChange} value={value} />
 *        <button onClick={() => onChange('test')}>change value</button>
 *      </>
 *    },
 *  }
 *
 *  const Template = {
 *    render: function Render (args) {
 *      const [ val, onClick ] = useControlledProps({ valueProp: 'val', changeProp: 'onClick' })
 *      return <>
 *        <InputField {...args} onClick={onClick} value={val} />
 *        <button onClick={() => onClick('test')}>change value</button>
 *      </>
 *    },
 *  }
 */
export const useControlledProps = (params) => {
  const {
    valueProp = 'value',
    changeProp = 'onChange',
  } = params || {}
  const [args, setArgs] = useArgs()
  const [value, setValue] = useState(args[valueProp] || '')

  useEffect(() => {
    setValue(args[valueProp])
  }, [args[valueProp]])

  const onChange = (value) => {
    args[changeProp](value)
    setArgs({[valueProp]: value })
    setValue(value)
  }

  return ([value, onChange])
}

It worked in v8. To make it work in v10 I had to change

import { useState, useEffect } from 'react'
import { useArgs } from 'storybook/preview-api'

to

import { useState, useEffect, useArgs } from 'storybook/preview-api'

Now there are no errors but new problem appeared: if I edit the text in the middle, cursor (caret) jumps to the end. It probably happens because React has special processing of synchronous events from inputs and Storybook's versions of useState breaks synchronous chain. See here about it.

You can see how it works in v10 here (I updated the sandbox to Storybook v10):
https://stackblitz.com/edit/github-4dcmyf-dxz9z8wn?file=src%2Fstories%2FTextField.stories.jsx

Please consider updating the documentation and adding tests for controlled components.

See also:
#25673
#29189