What's the difference between a component and a variant in Figma?

A component is a reusable element: edit the main component and every instance updates. Variants are versions of the same component grouped in a component set and picked through properties such as Size or State.

When should I make a separate component instead of adding a variant?

When the two elements have a different layer structure or do a different job. A primary and an outline button share a structure, so they are variants. A delete confirmation dialog and a 404 screen don't, so they are separate components. Figma also recommends against grouping different icons as variants.

Why does Figma show a conflict in my component set?

Two variants in the set have the same combination of property values, for example both are Size=md, State=Default. Every variant needs a unique combination. Change a value on one of them to clear the conflict.

Is it OK to detach an instance for a quick fix?

Keep it rare. A detached instance stops receiving updates from the main component. If you detach often, the component is probably missing a property, a variant or a slot.

Figma components and variants: set them up right

A Figma component is a reusable piece of UI: edit the main component and every instance updates. Variants group versions of one component, such as a button's sizes and states, into a single component set. Getting it right early means choosing correctly between variants, component properties and separate components, and naming them to match the props in code.

I'm Hai Le, a UI/UX designer. The library I built for Joyme has more than 50 components, and I write the React components for this site myself. My beginner's Figma plan covers your first component on day four. This post is for the point where you have a few dozen components and the library starts getting hard to manage.

Feature names and shortcuts were checked against help.figma.com on October 4, 2026.

What are components, instances and variants?

Term	What it is	Example
Main component	The source you edit	The button on your "Components" page
Instance	A linked copy of the main component	The button on a sign-up screen
Component set	The group that holds a component's variants	"Button"
Variant	One version inside the set	Button, Size=md, State=Hover
Override	A change made on a single instance	Label changed from "Send" to "Save"

Create a component with Option + Command + K on Mac or Ctrl + Alt + K on Windows. Instances pick up every change to the main component except the parts you've overridden.

How do you create variants?

There are two routes:

From one component. Select the main component and click Add variant in the right sidebar or the right-click menu. Figma creates the component set and adds a new variant next to the original.
From existing components. Select them and click Combine as variants in the right sidebar.

If your older components use slash naming, Figma turns the names into properties. Button/md/Default produces a component set called Button, and each segment after a slash becomes a value of one property. Every component in the group needs the same number of slashes.

The rule that matters most: all variants share the same properties, but each one must be a unique combination of values. Two variants with the same combination trigger a conflict that you have to resolve.

Variant or component property?

Figma has five types of component property. Variant is only one of them.

Property	Controls	Example
Variant	Visual versions of a component	Size, State, Type
Boolean	Whether a layer is visible	Show icon
Text	Editable text content	Button label
Instance swap	Which nested instance is used	The leading icon
Slot	A flexible area for any content	The body of a card or modal

The reason to prefer properties is multiplication. A button with 3 sizes, 4 states and 3 types needs 36 variants. Add "with icon / without icon" as a variant and you have 72. Make it a boolean and you stay at 36, while an instance swap property handles which icon appears.

My short version:

Differences in color, size, border or state: variant.
Whether a layer is there or not: boolean.
Different text: text property.
A different nested instance: instance swap, with preferred instances so people pick from an approved set.
A whole area of different content: slot. Use Convert to slot from the right-click menu or the right sidebar, or press Command + Shift + S on Mac and Ctrl + Shift + S on Windows.

When should you split into a separate component?

The question I ask: do the two share the same layer structure? Same structure with different values is a variant. A different structure is a separate component.

Joyme's library includes a confirmation before deleting a page, an empty state, a 404 error, a lost-connection screen and a slow-loading screen. The Joyme mascot appears in all of them, so at a glance they look like one family. A delete confirmation and a 404 page do different jobs, though. Forcing them into one component set because they share a mascot fills every variant with hidden layers that exist only to keep the structures aligned. You can see those states in the Joyme case study.

Figma calls out one case directly: don't use variants to group different icons. Different sizes of the same icon are fine.

How do nested instances and swapping work?

A button usually contains an icon instance. That's a nested instance, and by default people have to click deep into the button to change it.

Two ways to make that easier:

Turn on Expose properties from nested instances in the main component's Properties section. The icon's properties then appear next to the button's in the right sidebar.
Add an instance swap property for the icon, with a list of preferred icons.

To replace an instance with a different component, click the component name in the right sidebar to open the Instance menu, or right-click and choose Swap instance. You can also hold Option (Mac) or Alt (Windows) while dragging a component from the Assets tab onto an instance.

Figma tries to keep your overrides when you switch variants or swap. Give text layers distinct names so edited text survives the switch. A library where every text layer is called "Text" loses edits.

Why does my component library feel messy?

Symptom	Cause	Fix
Hundreds of variants in one set	Every difference became a variant	Move show/hide to booleans, icons to instance swap
Conflict warning in the set	Two variants share a combination	Change a value on one of them
Switching variants wipes edited text	Text layers named inconsistently	Give text layers consistent, distinct names
Screens full of detached instances	Component lacks a property or slot	Add what's missing, then swap the instances back
Developers can't find the matching component	Property names differ from code props	Agree on names with developers up front
States missing at handoff	Only the default state was designed	List empty, error, loading and disabled states before drawing

The last row is the lesson I took from Joyme. On a three-month timeline, states like lost connection or slow loading are the easiest to skip. The library still covered them, so developers didn't have to guess what they looked like.

How do variants map to props in code?

Each property type has a natural counterpart in a React component:

Figma	Props in code
Variant `Size` = sm, md, lg	`size: "sm" \| "md" \| "lg"`
Variant `State` = Hover, Focus	Usually CSS states, not props
Boolean `Has icon`	An optional `icon`, or a boolean prop
Text `Label`	`children` or `label: string`
Instance swap `Icon`	`icon: ReactNode`
Slot	`children`

The second row trips people up. Hover and Focus are variants in Figma because you need to see them, but in code the browser handles them with :hover and :focus-visible. Don't ask developers for a state prop.

The button on this site uses class-variance-authority with two axes, variant and size:

const buttonVariants = cva("…", {
  variants: {
    variant: { default: "…", outline: "…", ghost: "…" },
    size: { sm: "…", default: "…", lg: "…" },
  },
});

Those two axes correspond to two variant properties in Figma. When names match on both sides, a tool like Claude Code reading your file through the Figma MCP server can map them without guessing. Figma MCP with Claude Code explains the setup. The colors and spacing inside each variant should come from tokens, as described in what design tokens are, and the rules for which variant to use where belong in a file like DESIGN.md that people and AI can both read.

Where do you start if the library is already a mess?

Don't rebuild everything. Pick the most used component, usually the button or the text input, and work through it in order: list its props in code, rename properties to match, move show/hide differences to booleans, add the missing states. Finish one component before you start the next.

If the layout inside your components still feels shaky, read Figma auto layout explained first. And if you're hiring a designer who builds component libraries developers actually use, my about page has my experience and contact details.

Sources

Checked October 4, 2026.

Create and use variants, Figma Help Center
Explore component properties, Figma Help Center
Use slots to build flexible components, Figma Help Center
Swap components and instances, Figma Help Center
Create and insert component instances, Figma Help Center