Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Components and Variants

Nested Components and Swapping

Compose complex Figma components from smaller ones, swap nested instances without losing overrides, and organize components for reuse.

Real interfaces are built from layers of components. A product card contains a button, a badge and an avatar; a page header contains a logo, a menu and a search field. In Figma you can place an instance of one component inside another. This is called nesting, and it is how you build complex pieces from simple, trusted parts.

Figma cannot run on this site. Code in this lesson is a labelled JavaScript stand-in showing the ideas behind nesting and swapping. It is not Figma's real behavior in every detail.

Why nest?

Imagine a card that includes a primary button. If you drew the button inside the card as plain shapes, changing the brand color would mean editing the card too. If you place a button instance, the card follows the button component automatically. Nesting gives you a chain of updates: edit Button, and every Card, Dialog and Form that contains it updates, and so does every screen that uses those.

Atoms, molecules and organisms are a handy way to think about it:

  • Atoms: icon, button, input, avatar.
  • Molecules: search bar (input + button), list item (avatar + text).
  • Organisms: header, product grid, comment thread.
flowchart TD
    Icon --> Button
    Button --> SearchBar
    Input --> SearchBar
    SearchBar --> Header
    Logo --> Header
    Avatar --> Header

Small components build bigger ones; an edit at the bottom flows upward.

Building a nested component

  1. Create the small components first (Icon/Search, Button).
  2. Build the larger layout and drop instances from the Assets panel into it.
  3. Select the layout and create a component from it.

Inside the new component, the nested button is still an instance, so it keeps its own properties. Designers using the outer component can reach the nested instance's settings by selecting it, or you can expose them at the top level with component properties: for example, a "Button label" text property that controls the nested button's label.

Swapping instances

Select an instance and use the Swap instance control in the right panel, or the instance swap property if you exposed one. You pick another component and Figma replaces the instance in place. Position, size and overrides are kept when Figma can match them.

How does it match? Mostly by layer name. If the old component had a text layer named label with an override, and the new component also has a text layer named label, the override carries over. If the names differ, the override is lost. This is the strongest reason to name inner layers consistently across related components.

The stand-in below models that matching rule.

JS Stand-in: swapping keeps overrides by layer name

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Swapping to Button/Ghost keeps label and icon, and loses background because the ghost button has no such layer. Swapping to Chip loses everything because the names are different. The fix is not a clever setting; it is consistent naming when you design the components.

Keeping nested overrides tidy

Nested instances have their own overrides and sometimes you need to adjust one deep inside a parent. Select it (double-click into the instance, or hold Ctrl/Cmd and click on the canvas) and change its property. Figma remembers it as an override of the outer instance. If you later reset the outer instance, the nested overrides reset too.

Avoid chains deeper than three levels when possible. Past that, finding the instance that needs editing gets slow, and so does reading the layers panel.

Detecting problems

When you build a large file you will want to know how your components are organized. A small script can summarize usage from a tree; a stand-in follows.

JS Stand-in: count nested instance usage

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Organizing components for reuse

  • Put main components on a Components page, grouped by purpose, with section frames labelled "Buttons", "Inputs".
  • Use slash names (Form/Input/Text) to get a folder structure in the Assets panel.
  • Add a description to each component (right panel, "Description"). It shows in the Assets panel and in Dev Mode.
  • Publish the file as a library from the Assets panel so other files can use it; you will learn this in Building a Design System.

Modern Figma also supports slots, a way to let an instance accept arbitrary content (such as a card body that holds different layouts) without detaching. If your plan supports it, a slot is the right answer when instances need different structure inside one region, as an alternative to many variants.

Common mistakes

  • Detaching to tweak. One change in one place becomes a permanent exception. Ask whether a property would do.
  • Mismatched layer names between related components, which breaks override carry-over.
  • Over-nesting. Five levels of nesting are hard to debug.
  • Giant monolith components. If a component has many hidden parts, split it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why nest a Button instance inside a Card component?

    Nested instances follow their main component, so one edit flows upward through the chain.
  2. 2. When you swap an instance, how does Figma usually keep overrides?

    Matching layer names let overrides carry over; mismatches lose them.
  3. 3. Which is the best fix for instances that need different structure inside one region?

    Slots allow flexible content in one region without detaching.
  4. 4. Which nesting depth is a sensible upper limit for easy maintenance?

    Deep chains make it slow to find and edit the right instance.

Summary

  • Nesting places component instances inside other components so changes flow upward.
  • Swapping keeps overrides when layer names match, so name inner layers consistently.
  • Keep nesting shallow and components focused; use slots for flexible regions.
  • Organize components on a dedicated page with slash names and descriptions.

Next: Prototyping Basics