What is a Component Variant?

TL;DR

• A variant is a controlled alternative within one component family.
• Variants can represent purpose, size, state, emphasis, or configuration.
• Examples include primary vs. secondary buttons or compact vs. comfortable table rows.
• Variants should reflect reusable product differences, not every one-off exception.
• Clear properties make variants easier to use in design and code.

What does a component variant look like?

A button component may have variants for primary, secondary, and destructive intent, plus sizes and states such as default, hover, focus, loading, and disabled.

The family stays conceptually one component while supporting meaningful differences.

Variant vs. state

A state describes a temporary condition such as hover or disabled. A variant often represents a stable configuration such as intent or size.

Design tools may model both through variant properties, but the conceptual distinction helps teams reason about behavior.

Why do variants matter?

Without controlled variants, teams duplicate components and manually restyle them, increasing inconsistency and maintenance cost.

How do teams define variants?

1. Identify recurring meaningful differences.
2. Name the property clearly.
3. Limit values to real product needs.
4. Document when each variant should be used.
5. Keep design and code properties aligned.

Common mistakes

Variant explosion

Dozens of combinations make the system difficult to understand.

Using variants for one-off hacks

Fix the underlying design need or create a different component when appropriate.

Ambiguous names

“Style 2” gives no usage guidance.

The bottom line

A component variant asks: which controlled differences should this reusable component support without becoming a new component?

Related terms

Component · Component library · Design system · Design token

Relevant Figr resource

Read Design System Creation and Implementation.