[RFC]: Collapsed-by-default categories in the Controls args table

[eliasthompson]

Summary

Add a parameters.controls.categories parameter that lets users mark args-table categories as collapsed by default, in both the Controls panel and the ArgTypes/Controls doc blocks. Because it's a plain-object parameter, Storybook's standard parameter inheritance provides layered configuration for free: a global default in preview.ts, overridable per component or per story. The rendering component already supports this — SectionRow has an initialExpanded prop that is never wired to any public API — so this RFC is primarily about exposing existing behavior.

Problem Statement

Design systems increasingly add shared cross-cutting props (layout, spacing, accessibility passthroughs) to every component. Grouping them with table.category keeps the args table organized, but every category always renders fully expanded, so a component's own distinctive props get buried under dozens of rows of shared boilerplate on every single story. Users can collapse a category by clicking its header, but that state resets on every story navigation, making it useless as a curation tool.

Maintainers currently have no way to say "this category is reference material — keep it available, but out of the way." The existing escape hatches all sacrifice documentation: controls.exclude and table.disable remove the props entirely, and controls.sort reorders but doesn't reduce noise.

This was previously requested in #18487 (2022). It was closed as not planned in May 2026, with the closing comment inviting a fresh RFC — this is that RFC.

Non-goals

• Persisting a user's manual expand/collapse across stories or sessions. This RFC only sets the initial state; interactive toggling behaves exactly as today.
• Category ordering. Already resolved — categories follow argTypes declaration order.
• Hiding or filtering controls. controls.exclude / table.disable already cover that.
• Sidebar/story-tree collapsing. Different surface, tracked separately (Option to expand categories by default #16066).

Implementation

Proposed API — an object map keyed by category label (the same strings used in table.category):

// .storybook/preview.ts — global default
export default {
  parameters: {
    controls: {
      categories: {
        Layout: { collapsed: true },
        'HTML attributes': { collapsed: true },
      },
    },
  },
};

// Flex.stories.tsx — this component is ABOUT layout, so expand it here
const meta = {
  component: Flex,
  parameters: {
    controls: {
      categories: {
        Layout: { collapsed: false },
      },
    },
  },
};

The object-map shape is deliberate: combineParameters deep-merges plain objects across the global → component → story levels, so a component can override one category without restating the rest of the global config. (An array like collapsedCategories: string[] would be replaced wholesale by the more specific level — see Alternatives.) An object per category also leaves headroom for future per-category options without new top-level parameters.

Wiring is small because the UI already supports it:

• SectionRow (code/addons/docs/src/blocks/components/ArgsTable/SectionRow.tsx) already accepts initialExpanded?: boolean (default true); it is currently never passed by either call site.
• ArgsTable (.../ArgsTable/ArgsTable.tsx) renders a SectionRow per category and subcategory. It gains a prop carrying the categories config and passes initialExpanded: !categories?.[label]?.collapsed at both call sites.
• The Controls panel and the ArgTypes/Controls doc blocks (which share this ArgsTable component) read parameters.controls.categories and thread it through, alongside the existing handling of controls.sort / controls.expanded.
• Type the new key on the controls parameter types so it's autocompleted in CSF.

Prior Art

• Allow toggling the display of a category of controls and allow ordering of category #18487 requested exactly this in 2022 and accumulated the use case above; closed as not planned for lack of traction, with an explicit invitation to re-propose via RFC.
• Property inspectors in comparable tools treat grouped props as foldable with configurable defaults: IDE settings trees, browser devtools sections, and design-tool property panels all ship sections collapsed when they're secondary.
• Within Storybook itself, controls.sort, controls.expanded, and controls.exclude establish the pattern of table-presentation options living under parameters.controls with inheritance.

Deliverables

1. Parameter plumbing: parameters.controls.categories threaded through the Controls panel and doc blocks into ArgsTable → SectionRow, plus TypeScript types.
2. Tests: unit coverage for the category-config resolution and stories for ArgsTable in collapsed/expanded/override states.
3. Docs: update the Controls essentials page and the parameters API reference.

This fits comfortably in a single small PR; listed as three deliverables only for review clarity.

Risks

• Discoverability: a collapsed category might make users think props are missing. Mitigation: collapsed sections keep their labeled header row; we could additionally render the item-count caption (today shown only for subsections) at the category level when collapsed.
• Label coupling: config is keyed by the user-facing category string, so renaming a category silently orphans the config. This mirrors how table.category itself works, but worth stating.
• Expectation creep: users may expect their manual toggles to persist once defaults are configurable. Explicitly out of scope (Non-goals), but the API doesn't preclude adding persistence later.

Unresolved Questions

• Subcategory support: nested config (categories: { Layout: { collapsed: true, subcategories: {...} } }) vs. a path key ('Layout/Spacing') vs. category-level only for v1?
• Should a collapsed category header show an item count (currently only subsections do)?
• Parameter naming: controls.categories (proposed) vs. something more explicit like controls.categoryDefaults?
• Should the docs blocks respect parameters.controls.categories, or do docs need an independent parameters.docs-level override?

Alternatives considered / Abandoned Ideas

• collapsedCategories: string[] — simplest shape, but combineParameters replaces arrays wholesale at more specific levels. A component wanting to expand one globally-collapsed category would have to restate every other global entry, which rots as the global list changes. The object map deep-merges and avoids this.
• Per-argType table.initialExpanded — puts the setting on individual args, but a category spans many args, so conflicting values need arbitrary tie-breaking, and it's maximally verbose for the common "collapse this shared category everywhere" case.
• Userland workarounds (status quo) — a manager-head.html MutationObserver that auto-clicks section toggles (fragile, flashes, breaks silently on DOM changes) or patch-package against bundled dist files (breaks on every Storybook upgrade). Both exist in the wild precisely because there's no supported option.