Back to Blog
April 29, 2026Thiago Patriota

Figma Component States: 2026 Guide + Best Practices

Figma Component States: definitions, examples, and best practices to model variants, avoid bloat, and speed developer handoff. Read now.

Figma Component States: 2026 Guide + Best Practices

Figma Component States: 2026 Guide + Best Practices

figma component states

TL;DR

Figma component states are the named conditions a reusable UI component can appear in, such as default, hover, pressed, focus, disabled, loading, error, and success. They are most often built as variants inside a component set, but not every state-like difference should become a variant. Simpler changes belong in component properties or variables. Getting this right prevents variant bloat, speeds up developer handoff, and keeps your design system honest about what the product actually does.


What Are Figma Component States?

A component state is a specific condition a reusable UI element can be in. When a button can look and behave differently depending on whether it is resting, hovered, pressed, focused, disabled, or loading, each of those conditions is a state.

In Figma, component states are usually represented as variants inside a component set. A variant is a specific version of a component that differs in a predictable, named way. You define a property like State with values such as Default, Hover, Pressed, Focus, and Disabled, and Figma groups them inside a dashed purple container called a component set.

But variants are not the only tool. Figma also offers component properties (booleans, text, instance swaps) and variables with modes for differences that do not warrant a full variant. The art of managing Figma component states is knowing which tool fits which kind of change.

Here is a distinction that matters: a component state should explain what the product does, not merely what the layer looks like. A hover color alone is not enough. A developer needs to know what triggers the state, whether it is keyboard-accessible, and how it maps to code. That is the difference between a Figma file that looks polished and one that actually ships well. For more on how design and engineering intersect in practice, see the intersection of design and technology.


Common Examples of Component States

Not all states are the same. They fall into three broad categories, and understanding the differences prevents messy component sets.

Interaction States

These are temporary conditions caused by user input.

State Meaning CSS Equivalent
Default Resting state before any interaction Normal styling
Hover Pointer is over the component :hover
Pressed / Active User is clicking or tapping :active
Focus Keyboard or assistive-tech focus is on the component :focus, :focus-visible

Semantic / Product States

These represent meaningful status in the product and tend to be persistent.

State Meaning Notes
Selected / Current Item is chosen or represents current location Not the same as pressed
Error / Invalid Input or action failed validation Needs message, icon, accessible text
Success Input or action completed Often temporary
Warning Attention needed but not blocking Usually informational

System / Async States

These are caused by loading, permissions, or backend responses.

State Meaning Notes
Loading Action started, result pending Often paired with spinner or progress text
Disabled Component is unavailable Should not rely only on low opacity
Read-only Visible but not editable Different from disabled semantically
Empty No content to display Needs guidance or placeholder
Skeleton Content is loading, shape shown Reduces perceived wait time

The Design Systems Collective recommends always creating default, hover, active/pressed, focus, disabled, and loading when relevant for interactive elements. MDN documents these as user-action pseudo-classes, which is the language developers already use.

This taxonomy connects directly to broader UI patterns. A toggle, a form field, and a navigation tab all need states, but the specific states they need differ.


When to Use Variants, Booleans, or Variables

This is where most teams get stuck, and where the real decisions happen. Every state-like difference in a component does not need to be a variant. Figma gives you several tools, and using the wrong one creates unnecessary complexity.

The State Modeling Ladder

Before creating variants, walk through these questions in order:

1. Is it only content?
Use a text property. Button labels, input placeholders, and error messages change without needing a new variant.

2. Is it only show/hide?
Use a boolean property. Figma describes boolean properties as toggles for layer visibility, like showing or hiding an icon on a button.

3. Is it a replaceable child?
Use an instance swap property. If the state involves switching an icon, avatar, or badge, instance swap keeps the component flexible without variant multiplication.

4. Is it a system-wide visual mode?
Use variables and modes. Figma’s variable system can map string and number variables to variant instances, so a component switches variants automatically when the mode changes (light to dark, for example).

5. Is it a meaningful condition of the component?
Now use a variant. The state changes the component’s structure, behavior, or code prop. It needs to be selectable from a dropdown, inspectable by a developer, and documented.

6. Is it a different semantic component?
Make a separate component entirely. A button and a link are not states of each other. Neither are a checkbox and a switch, even though they look similar. The WAI-ARIA switch pattern explains that switches, checkboxes, and toggle buttons have different semantics despite functional overlap.

This ladder prevents unnecessary variant bloat while keeping meaningful states visible for design, QA, and development. For teams building design systems at scale, it is the single most important framework to internalize.


Example: Button Component States in Figma

A button is the classic example. Here is a well-structured button component:

Component: Button
Type: Primary | Secondary | Tertiary        → variant property
Size: Small | Medium | Large                 → variant property
State: Default | Hover | Pressed | Focus | Disabled | Loading → variant property
Icon left: true | false                      → boolean property
Icon right: true | false                     → boolean property
Label: "Button"                              → text property
Theme: light / dark                          → variables/modes

Interaction states live in the State variant property. Optional icons are booleans. Theme is handled through variables, not duplicated variants.

The Variant Explosion Problem

Without this discipline, the math gets ugly fast. Consider a button with:

  • 3 types (primary, secondary, tertiary)
  • 3 sizes (small, medium, large)
  • 6 states (default, hover, pressed, focus, disabled, loading)
  • 2 icon settings (with/without)
  • 2 themes (light/dark)

The naive variant count: 3 x 3 x 6 x 2 x 2 = 216 variants.

With better modeling:

  • Keep Type, Size, and State as variants: 3 x 3 x 6 = 54
  • Handle icons with booleans
  • Handle themes with variables

That is a 75% reduction. And it matters for more than just tidiness. Figma’s own documentation warns that when an instance with variants is added to a file, Figma imports every variant in that component set, and large component sets can affect speed and performance.

Practitioners on Reddit confirm this. In a FigmaDesign thread about button variants, one commenter advised using a boolean property for icons to cut variants in half. Another warned that Figma loads every variant of a component into memory for each instance, so minimizing unnecessary variants is not just organizational preference but a performance concern.

Figma’s own Schema 2025 recap reported that their design-system infrastructure rewrite made updating variables or switching modes 30 to 60% faster, reducing some heavy state swaps from 3500ms to 350ms. That improvement only matters if you are working with components complex enough to hit those limits.


Focus, Hover, Active, and Selected Are Not the Same

This is one of the most common sources of confusion when modeling Figma component states. These four conditions look similar on the surface, but they mean different things, trigger differently, and serve different users.

Hover is pointer-specific. A mouse or trackpad user moves over the element. Touch users never see it. It maps to CSS :hover.

Active/Pressed is the momentary state during a click or tap. It maps to CSS :active. It is almost always fleeting.

Focus means the element has keyboard or assistive-technology focus. It maps to CSS :focus or :focus-visible. This is the one teams skip most often, and it is the one that matters most for accessibility. WCAG’s Focus Visible criterion says the purpose is to help a person know which element has keyboard focus. WCAG 2.2 adds that a focused component should not be entirely hidden by author-created content like sticky headers or overlays.

Selected/Current is a persistent product state. A tab is selected. A row is current. A filter is active. Selected is not pressed. It persists after the click ends.

The practical problem is that focus often needs to combine with other states. A selected tab can also be focused. An error input can also be focused. This creates a modeling headache.

Practitioners on Reddit debate this actively. In one FigmaDesign thread, a user asked whether focus should be a boolean because combining default, focus, hover, selected, and disabled creates too many variants. Commenters agreed focus is critical for accessibility but disagreed on implementation. One described a State dropdown with default, hover, focus, selected, and disabled. Another accepted a boolean approach for combinations like selected-focus.

In a related thread, a designer described creating a reusable focus-ring component, just a stroke, placed as an absolutely positioned object with edge constraints and controlled by a boolean show/hide property. Other commenters noted this works well because focus is independent of hover or active.

The recommendation: if focus is only an outer ring that must stack with selected, error, or active states, model it as a boolean overlay. If focus changes the component’s layout, color logic, or API, make it an explicit state variant.


Interactive Components and Prototype States

Figma’s interactive components let you connect variants with prototype interactions. A button can visually switch from default to hover to pressed inside a prototype without creating separate frames for each.

This is useful for demonstrating behavior to stakeholders. It reduces prototype complexity. But it is not a substitute for documentation.

A prototype that visually switches from default to hover does not automatically tell a developer how to implement hover, focus, disabled, loading, or async behavior in production. Figma prototypes can memorize and share state across frames, and designers can disable this with “Reset component state” in the interaction details panel. These are prototype mechanics, not production specs.

The distinction matters because teams working on complex software (especially agentic and AI-enabled products) need to communicate system states like loading, error recovery, permission changes, and async feedback. Those states are rarely prototyped but always need to be built.


Why Component States Matter for Developer Handoff

The recurring handoff problem is not missing mockups. It is missing states. Practitioners on Reddit describe this pattern consistently. In one FigmaDesign discussion about design-to-code handoff, commenters said the recurring problem is forgetting error states and edge cases until development. One commenter described an internal tool that lists components used in a selected layer and adds code-call descriptions and design-system links. A developer called it “the best file” they had received from a UX designer.

Figma’s own handoff guidance says developers may need information about whether a component belongs to the design system, whether it is project-specific, and which overrides have been applied. Smashing Magazine’s handoff guide adds that developers need details like hover state, initial state, max width/height, and outcomes of different use cases.

A State Documentation Table

For every meaningful component state, consider documenting these fields:

Field Example (Loading State)
State name Loading
Trigger User submits form
Visual change Spinner replaces icon; label changes to “Saving…”
Interaction Button ignores duplicate clicks
Accessibility Announce progress or keep label meaningful
Code mapping <Button loading disabled />
Token mapping button.bg.disabled, button.text.disabled
Related states Error, success, retry

This level of documentation turns a Figma file from a picture into a spec. If a developer cannot tell what triggers the state, the state is under-documented.

A LinkedIn practitioner post about design tokens recommends naming state colors by role rather than hex value, using names like button.bg.hover and button.text.disabled instead of raw color references. This makes theming easier and keeps handoff language consistent.

The 2026 zeroheight Design Systems Report found that satisfaction differs sharply across disciplines: 72% satisfaction for design implementation, but only 54% for code, 45% for documentation, and 44% for accessibility. Component states sit at the exact intersection of all four. Getting them right lifts every dimension.

For product teams dealing with slow design cycles and developer back-and-forth, clear component state documentation is one of the highest-return investments in a design system.


Accessibility Considerations

Component states are not just a design organization problem. Several states have direct accessibility implications.

Focus states must be visible. WCAG’s Focus Appearance guidance explains that a focus indicator should have sufficient size and contrast. People who cannot use a mouse rely on seeing which element has keyboard focus.

Focus indicators must not be hidden. Sticky headers, footers, modals, and overlays can obscure focused elements. WCAG 2.2’s Focus Not Obscured criterion explicitly addresses this.

Do not rely on color alone. A red border on an error input helps sighted users, but the state also needs a text message and, ideally, an icon or ARIA attribute so that all users understand the condition.

Disabled states need context. Lowering opacity to 50% tells a sighted user something is off, but it does not explain why. Consider explaining the reason for unavailability near the component.

Semantic role matters. A switch and a checkbox can look alike, but the WAI-ARIA switch pattern makes clear that authors should choose the role matching the visual design and semantics. This is a state-level decision, not just a component-level one.

The zeroheight report noted that roughly 4 in 10 design systems do not include accessibility guidelines. That gap shows up directly in component states: teams build hover and pressed variants but skip focus states entirely.


Common Mistakes

Putting every difference into variants. Not every change is a state. Icon presence, label text, and theme are not states. Use the state modeling ladder.

Using visual names instead of semantic names. “Gray button” and “blue button” are less useful than “disabled” and “primary.” Semantic names travel from design to code to documentation without translation.

Skipping focus states. Keyboard users need a visible focus indicator. This is not optional polish; it is a WCAG requirement.

Using inconsistent layer names across variants. Figma’s override preservation depends on matching layer names and similar hierarchy. If layer names differ between your Default and Hover variants, designers lose text and icon overrides when switching states. Practitioners on Reddit report that hover interactions that work alone can reset icons or text when nested inside another component due to naming mismatches and variant connection issues.

Documenting only the happy path. Error, empty, loading, partial, and permission states are often the ones developers need most. They are also the ones most likely to be forgotten until someone opens a bug ticket.

Treating prototype behavior as production behavior. Interactive components show intent. Developers still need trigger rules, accessibility requirements, and edge-case specs.

Ignoring design-code parity. A DesignSystems thread from 2026 notes that parity breaks down specifically around nested components, variants, states, and structural alignment with code. Component states are a parity problem, not only a Figma organization problem.

Twitter’s engineering blog provides a useful proof point: updating button border radius on their legacy desktop site required manually updating and visually verifying 442 different button instances, while the same change on their componentized codebase took far fewer engineers just two weeks. When states are ad hoc, every design change becomes manual QA.


Quick Checklist

Use this before publishing a component to your design system:

  • Does every interactive component have default, hover, pressed, focus, and disabled states where relevant?
  • Are selected/current states separated from pressed states?
  • Are error, success, loading, empty, and read-only states documented where relevant?
  • Are optional icons and content modeled with booleans or instance swaps instead of duplicate variants?
  • Are themes handled with variables and modes instead of duplicated light/dark variants?
  • Do variant names match code or Storybook names where possible?
  • Are focus states visible and accessible?
  • Do layer names match across all variants to preserve overrides?
  • Are edge cases shown in the handoff file or component documentation?
  • Has the component been tested inside nested parent components?

If the answer to more than two of these is “no,” the component is not ready for handoff. For SaaS teams scaling product delivery, these gaps compound fast across dozens of components.

Teams that need help cleaning up component states, aligning Figma libraries with code, or documenting design systems for developer handoff can discuss a Figma component audit with Thiago Patriota.


FAQ

What are component states in Figma?

Component states are the named conditions a reusable UI component can appear in, such as default, hover, pressed, focus, disabled, selected, loading, error, and success. In Figma, they are typically built as variants inside a component set and exposed through a property like State.

How do you create button states in Figma?

Create a button component, then add variants for each state (Default, Hover, Pressed, Focus, Disabled, Loading). Use a variant property named State to organize them. Keep optional elements like icons as boolean properties to avoid variant explosion.

Should hover and focus be separate variants in Figma?

Yes, they should be separate because they serve different users and trigger differently. Hover is pointer-specific. Focus is for keyboard and assistive-technology users. If focus is only a visual ring that overlays other states, consider a boolean property instead of a full variant.

What is the difference between a Figma variant and a component state?

A component state is the concept (the condition the component is in). A variant is one of Figma’s implementation tools for representing that state. Not all states need to be variants. Simple show/hide differences work better as boolean properties, and theme-level differences belong in variables.

How do you avoid too many variants in Figma?

Use the state modeling ladder. Reserve variants for meaningful state changes. Handle optional content with boolean properties, replaceable children with instance swaps, text changes with text properties, and themes with variables and modes. A button does not need 216 variants if properties and variables handle icon, label, and theme differences.

How do Figma component states help developer handoff?

Clear component states reduce questions and rework during development. When states are named, documented with triggers and accessibility notes, and aligned with code APIs, developers can inspect the component in Figma and know exactly what to build. Missing states, especially error, loading, and empty, are the most common source of handoff friction.

Do Figma interactive components replace state documentation?

No. Interactive components let you prototype transitions between states (default to hover, for example), which helps demonstrate intent. But they do not specify triggers, accessibility behavior, code mappings, or edge cases. Documentation is still required.

What states should every interactive component include?

At minimum: default, hover, pressed, focus, and disabled. Beyond that, include loading, selected, error, success, empty, and read-only states where the component’s purpose requires them. The specific states depend on the component’s role in the product.


For broader resources on interface craft, component documentation, and design tooling, explore the UX/UI design library and design tools and workflows collection. Designers looking for deeper design-system thinking can find ongoing references at resources for design peers.