Limits of Storybook addon-controls with non-serializable props in 6.x and 7.x

Answer

There is no documented or supported mechanism to replace or extend the JSON‑stringify based serialization used by Storybook’s @storybook/addon-controls panel in versions 6.x and 7.x. The serialization logic is hard‑coded in the core controls implementation, so non‑serializable values (functions, symbols, undefined, circular objects, BigInt, etc.) are always replaced by a non‑editable placeholder or omitted from the controls list.

Why this happens

• When the controls panel reads a story’s args, it runs JSON.stringify(value) on each prop to produce a displayable representation.
• If JSON.stringify throws or returns undefined for a value, the panel shows a placeholder (e.g., "[Function]", "[Circular]") that cannot be edited, or it simply hides the control.
• No addon parameter, preset, or feature flag exists to inject a custom serializer or to supply a fallback string for such values.

Recommended boundary for using controls

To avoid misrepresenting a component’s testability, keep the controls panel limited to JSON‑serializable args only. For props that are functions, circular objects, or other non‑serializable values:

1. Exclude them from controls – use the story‑level or global parameters.controls to disable or filter those props:

// .storybook/preview.js (global)
export const parameters = {
  controls: {
    exclude: ['onClick', 'onChange', 'complexObj'] // prop names to hide
  }
};

// or per‑story
export const parameters = {
  controls: { exclude: ['onClick'] }
};

2. Provide the real value via a decorator or manual args – keep the prop in the story’s args but give it a serializable placeholder (e.g., an object with a name field) and restore the actual function/object in a decorator:

// story.js
export const MyStory = {
  render: (args) => <MyButton {...args} />,
  args: {
    onClick: { name: 'onClick' }, // serializable placeholder
    label: 'Click me'
  },
  parameters: {
    controls: { include: ['label'] } // only show label in controls
  },
  decorators:[(Story) => {
    const story = Story();
    // replace placeholder with the real function
    story.props.onClick = () => alert('clicked');
    return story;
  }]
};

3. If you only need to inspect the prop name, you can keep the placeholder and rely on the decorator to restore the real value; the control will remain disabled, but the prop name is still visible in the args table.

Verification steps (safe, scoped)

1. Create a fresh Storybook 6.x or 7.x project (e.g., npx sb init).
2. Add a story with a function prop and a circular object prop:

export const FunctionStory = {
  render: (args) => <div onClick={args.onClick}>Click</div>,
  args: { onClick: () => console.log('clicked'), circular: { a: 1 } }
};
// make circular
FunctionStory.args.circular.self = FunctionStory.args.circular;

3. Run npm run storybook and open the Controls panel.
4. Observe that the onClick control appears as a disabled placeholder (or is missing) and the circular is either omitted or shown as a non‑editable "[Circular]".
5. Attempt to edit the placeholder – the UI will not accept changes, confirming the lack of serialization support.
6. Remove the function from args or exclude it via parameters.controls.exclude and verify that the remaining controls become editable.