If you copy and paste the same button fifty times across a Figma file, every change becomes a chore. Change the corner radius and you have fifty buttons to fix, and you will miss a few. Figma components solve this. You design an element once, reuse it everywhere, and every copy updates when you change the original.
Variants and component properties take this further: one component can represent every size, state and style of a button, controlled from a few clear options in the right sidebar. This guide explains the ideas in plain language, walks through building a button, and lists the mistakes that make Figma components painful to use. It is based on Figma’s current help documentation.
Figma components: main components and instances
A main component is the source. It defines how the element looks and behaves. An instance is a linked copy that you place in your designs. When you edit the main component, every instance receives the change.
- To create a component, select a frame or layers and press Ctrl + Alt + K on Windows (Cmd + Option + K on Mac), or click the Create component button in the toolbar.
- To create an instance, copy and paste the main component, or drag it from the Assets panel.
- Main components show a four-diamond icon in the layers panel; instances show a single hollow diamond.
- To go from an instance to its source, right-click and choose the option to go to the main component.
Tip: Build your components with Auto layout from the start. A button made with Auto layout grows with its label; a button made from a fixed rectangle and a text layer does not.
Overrides: what you can change in an instance
An instance does not have to be identical to its main component. You can change text, colours, effects, the visibility of layers and nested instances. These changes are called overrides. If the main component later changes something you have not overridden, the instance still updates.
What you cannot do in an instance is change its structure: you cannot delete or reorder layers or add new ones directly. If you need that, the usual escape is Detach instance (Ctrl + Alt + B on Windows, Cmd + Option + B on Mac), which turns it back into a plain frame. Detaching breaks the link, so the copy will never receive updates again. Treat it as a last resort.
Watch out: If your team detaches instances often, the component is missing a property it needs. Fix the component instead of detaching copies.
Variants: one component, many versions
A button usually comes in several versions: primary and secondary, small and large, default, hover and disabled. Before variants, people made a separate component for each combination, with names such as “Button/Primary/Large/Hover”. Variants group these into a single component set with named properties.
To add a variant, select a main component and use the add-variant option in the right sidebar, or right-click it and choose Add variant. Figma duplicates the component and wraps both copies in a component set with a dashed purple border. Each variant property is a dimension, and each variant has a value for every property.
| Variant property | Values | Example |
|---|---|---|
| Type | Primary, Secondary, Ghost | Main call to action vs a less important action |
| Size | Small, Medium, Large | Compact table actions vs a large mobile button |
| State | Default, Hover, Pressed, Disabled | Interactive states for prototypes and handoff |
When someone places this button, they see three dropdowns in the right sidebar instead of hunting through a long list of separately named components. The default variant is the one in the top-left corner of the component set.
If you already have separately named components that use slash naming, select them and choose Combine as variants. Figma uses the names to create the properties and values for you.
Component properties: fewer variants, more control
Variants multiply quickly. Three types × three sizes × four states is already 36 variants. Add “with icon” and “without icon” and you have 72. Component properties let you handle many of these differences without creating a new variant for each. Figma currently offers these property types:
| Property | What it controls | Button example |
|---|---|---|
| Variant | Switches between versions in a component set | Type, Size, State |
| Boolean | Shows or hides a layer (true/false) | Show left icon: on/off |
| Text | Lets people edit a text layer from the sidebar | Label: “Book a table” |
| Instance swap | Lets people swap a nested instance, with a list of preferred options | Icon: arrow, plus, download |
| Slot | A flexible area where people can add, rearrange and edit their own content inside an instance | Not usually needed for a button; useful for cards, lists and modals |
With a Boolean property for the icon, your 72 variants drop back to 36. A Text property means nobody has to dig into nested layers to change a label. An Instance swap property, with a short list of preferred icons, stops people from dropping random icons into your buttons.
Slots are one of the newest property types. They are designed for components with repeating or freeform content, such as a card whose body changes from screen to screen, so designers do not need to detach the card. Because this feature is recent, check Figma’s help centre for its current behaviour before you build a library around it.
Step by step: build a button component
- Create a text layer “Button” and an icon instance next to it. Select both and press Shift + A to add Auto layout. Set padding 12 × 20, gap 8, and Hug for width and height.
- Add a fill, a corner radius and, ideally, colour variables instead of raw hex values.
- Press Ctrl + Alt + K to make it a component. Name it “Button”.
- Select the label and, in the right sidebar, create a Text property called “Label”.
- Select the icon and create a Boolean property “Show icon” for its visibility, and an Instance swap property “Icon” with a few preferred icons.
- Add a variant. Rename the variant property to “State” and the values to “Default” and “Hover”. Add “Disabled” too.
- Add a second variant property, “Type”, with values “Primary” and “Secondary”, and style each combination.
- Arrange the component set in a neat grid, with Default in the top-left so it becomes the default.
- Place an instance in a design and test every dropdown, toggle and text field. Try a very long label.
For prototypes, you can then use interactive components: connect the Default variant to the Hover variant with a “While hovering” interaction, and every instance in every prototype gets the hover effect. See Prototyping in Figma for how prototypes work.
Naming and organising Figma components
- Name components by what they are, not how they look: “Button”, “Input”, “Card”, not “Blue box”.
- Use the same property names across components. If buttons use “Size: Small / Medium / Large”, inputs should too.
- Keep values short and consistent: “Default”, “Hover”, “Disabled” everywhere, not “Normal” in one place and “Rest” in another.
- Name layers inside components clearly (“Label”, “Icon left”). Developers inspecting the file in Dev Mode will see these names.
- Keep main components on a dedicated page (for example “Components”) and publish them as a library when several files need them.
- Write a short description for each component; it appears to people using it.
How variants relate to code
Variant and component properties map naturally to how developers build components. A React button might accept props such as variant="primary", size="lg", icon and children for the label. When your Figma properties use the same names and values as the code, handoff becomes far smoother. Ask your developers which names they use, or read our React props lesson to see the idea from the code side.
| Figma | Typical code equivalent |
|---|---|
| Variant property “Type” | A variant prop or a CSS modifier class such as .btn-primary |
| Variant property “State: Hover / Disabled” | CSS :hover and the disabled attribute, not a prop |
| Text property “Label” | The button’s text content (children in React) |
| Boolean “Show icon” | Conditional rendering of an icon |
| Instance swap “Icon” | An icon prop |
Notice that hover and disabled states usually come from the browser and CSS, not from props. Designing them as variants is still right, because developers need to see what each state looks like. The Bootstrap buttons lesson shows the same pattern in a real framework.
Common mistakes
| Mistake | Better approach |
|---|---|
| Creating a variant for every icon | Use an Instance swap property |
| Creating “with label” and “without label” variants | Use a Boolean property for the label layer |
| Hard-coding colours in each variant | Use colour variables, so a theme change is one edit |
| Building without Auto layout | Use Auto layout so content can grow and shrink |
| Huge component sets nobody understands | Split rarely used versions into a separate component |
| Detaching instances to make small changes | Add the missing property to the main component |
Where this leads: design systems
Once your buttons, inputs, cards and navigation are Figma components with clear properties, connected to colour, spacing and typography variables, you have the core of a design system. Read design systems for beginners for the next step, and CSS custom properties as design tokens to see how those variables become code. When your components are ready for development, use our design handoff checklist, and keep colours and text styles consistent with the principles in colour in UI design and typography for UI.
Frequently asked questions
What is the difference between a component and a variant in Figma?
A component is a reusable element with a main component and linked instances. Variants are versions of a component, such as different sizes or states, grouped into one component set and controlled by variant properties.
What is the shortcut to create a component in Figma?
Press Ctrl + Alt + K on Windows or Cmd + Option + K on Mac with a frame or layers selected.
When should I use a Boolean property instead of a variant?
Use a Boolean property when the only difference is whether a layer is visible, such as an icon or a badge. Use variants when the difference affects styling or layout, such as size or state.
Is it bad to detach an instance?
Detaching breaks the link to the main component, so that copy no longer receives updates. It is fine for a one-off experiment, but frequent detaching usually means the component needs another property or a slot.
Can I convert existing components into variants?
Yes. Select the components and choose Combine as variants. If they use slash naming, such as Button/Primary/Large, Figma uses the names to create the variant properties and values.
