A component with too many parameters cannot be used correctly
Aliases: boolean explosion · parameter overload · too many props
What it is
Every public parameter is a dimension. As dimensions pile up, legal combinations grow exponentially, while the combinations that were designed and tested stay close to the few happy paths in the author’s head. Callers see twenty switches in docs and autocomplete, and guess. A wrong guess still “uses the system”, and walks into a state that was never specified. Prop soup is what happens when the public surface outruns what can be held: correct use stops being the default. It does not care whether the abstraction came early or late, or whether one more repetition should have been waited for — the soup is already in the bowl, and the bowl cannot be ladled accurately.
Why it happens
N independent booleans yield 2^N configurations. Working memory will not hold that table, and docs rarely exhaust it. “Correct use” then lives only in the author’s example file; cells the examples do not cover get filled by caller intuition. Intuition turns on mutually exclusive switches together, stacks visual and semantic meaning under one name, and opens loading on top of empty. If the internals digest those combinations with a long chain of conditionals, undesigned cells fall into blank, misaligned, or mutually overriding styles. Outwardly, every call site writes its own dialect, because the soup has no recitable calling convention. More parameters, less chance of a convention: three to five usual pairings can be remembered; the rest are trapdoors. Once a trapdoor ships, deleting the parameter is a breaking change. Soup thickens itself: each misuse spawns “one more switch to forbid that misuse”.
Where it stops holding
Low-level primitives (native inputs, a stack) are legitimately parameter-heavy; that is the platform contract, carried by platform docs and language servers, not by a business component in a design system. A business component whose parameter count approaches a primitive has usually stuffed several duties into one name. A config object or a slot can make the surface look shorter; if the object is still an unconstrained bag of switches, the soup changed bowls. Variant panels in design tools cook soup too: too many axes and designers likewise cannot foresee combinations. If some combinations are illegal and the type system rejects them, the effective space shrinks — that is treating soup. Runtime warnings with types still wide open leave callers guessing while they type. A one-off local widget can bear more parameters, because its convention is that one call site; once shared, the convention must be able to leave the author’s head.
Applying it
- For each shared component, publish a short list of supported calling conventions: a handful of complete examples, each a real duty. Combinations outside the list are illegal — blocked by types or runtime asserts, not silently rendered.
- Make exclusive dimensions an enum, not two booleans. If the docs need a truth table, split into two components or compose, rather than adding a paragraph of “please do not turn both on”.
- Gate every new parameter: does it retire an existing convention, or open a trapdoor for one page. Trapdoors stay off the public surface.
- Check: take an engineer who has not written this component, give only the convention examples, and have them implement a middling screen. If the first call opens a switch the examples never showed, or they ask “can these two go together”, soup is already at work. Count public parameters and the legal combinations the types permit: legal combinations far above convention count are a culture medium for misuse. Open production call sites against the conventions; the breach rate is the measure of “cannot be used correctly”, not a vibe.