Component Properties: Levers Without Variants

WHY IT EXISTS: Before component properties, Figma designers managed every permutation of a UI element through variants. A single button could balloon into a grid of dozens of combinations for size, color, icon presence, and state. That matrix was brittle: change one corner radius and you might update thirty variants manually. Component properties were invented to collapse that combinatorial explosion into a single master component with configurable slots, so one source of truth could generate many permutations without the maintenance nightmare.

THE MENTAL MODEL: Think of a component property as a control panel wired directly into the master component. Instead of baking every possible version into the library, you expose levers. An instance in a mockup stays connected to the master, but the designer can flip switches to show or hide layers, edit text without overriding, or swap one nested icon for another. It is the difference between ordering a custom car from a configurator and maintaining a warehouse full of every possible configuration.

HOW IT WORKS: Figma offers four property types. Variant properties let you switch between predefined visual options like size or color. Boolean properties show or hide specific layers, such as an optional badge on an avatar. Text properties expose string fields so instance text can be edited without detaching. Instance swap properties let you replace a nested component, like trading a warning icon for a checkmark inside a button. You define these on the master component, and they appear as controls in the right sidebar whenever someone selects an instance.

WHEN TO USE IT: Reach for component properties when one dimension of a component changes frequently but does not require a wholly different visual structure. Buttons with optional icons, list rows with variable metadata, and form inputs with optional helper text are ideal. They also keep design systems cleaner because you ship fewer master components while still giving product teams flexibility.

WHEN NOT TO USE IT: Avoid them when every combination demands unique layout rules or spacing that cannot be handled by simple overrides. If a toggle hides a layer but the surrounding auto layout does not collapse the gap, you will create phantom whitespace. Also resist the urge to property-ify everything; once a component carries more than five or six controls, teammates often find it faster to browse a variant grid than to hunt through a long properties panel.

ONE CANONICAL EXAMPLE: Imagine a primary button component. You add a text property for the label so each instance can say Submit, Cancel, or Next. You add a boolean property called Show Icon that toggles an icon layer on or off. You add an instance swap property on that icon so designers can choose an arrow, a plus, or a download glyph. Finally, you keep size and color as variant properties. The result is one button component with a handful of controls instead of a sprawling matrix of twenty or thirty variants, and every instance stays connected to the same master.