Why Are My Nested Components Not Working in Figma?

A nested component is an instance placed inside another main component. A button that contains an icon instance, or a card that contains a button, are both nested setups. Edit the icon's main component and every button picks up the change. That's the reason to nest: one fix travels through the whole system.

1. Nested instances aren't exposed. Turn it on from Properties → Expose properties from → Nested instances, as in the steps above.
2. The option isn't there. Nested instances only appears if the component already has nested instances that have their own properties, or an instance that's already exposed. A plain nested icon with no properties has nothing to expose. Add properties to the nested component first.
3. A boolean hides the nested instance. If a boolean property hides an exposed nested instance, that instance's properties are hidden in the sidebar too. Toggle the boolean on to see them.
4. The library isn't updated. If the nested component comes from a library, the new properties arrive only after the library is published and you accept the update. See Figma library not showing.

You see this message when you drop an instance into a main component and Figma refuses it. Placing a button's instance inside the button's own main is the obvious case. The confusing case is indirect: if component A already contains B, putting A inside B would make a loop. Figma's help center doesn't document the message, so treat the loop as the likely explanation rather than a confirmed one.

To find the loop, open the component you're dropping in and check its layers for an instance of the component you're editing, including one nested deeper down. Remove or swap that instance, and the drop will work.

This one shows up in prototypes as "Couldn't play interaction: nested instance is swapped with parent instance". Figma doesn't document it, but a forum thread with over 23,000 views collected these fixes from people who hit it:

• Make sure every variant in the set has the same nested layer structure. One variant with an extra group or a duplicate instance can trigger it.
• Look for an instance of the component inside one of its own variants. Detach it, then publish the library again.
• If one variant keeps causing it, delete that variant and rebuild it from a working one.

Some edits are never allowed on an instance, however deep it is: layer order, position, constraints and text layer bounds. That's why you can't drag an icon to a new spot inside a button instance or resize a text box inside a card. Make those changes on the main component, which you can reach with Go to main component. If the main component sits in a library, hover the library name in the right sidebar and choose Go to main component in library.

Detaching to get around these limits breaks the link for good. A nested instance can't be detached on its own either: you'd have to detach the parent first. The detach instance guide covers that. If you need a flexible area where instances can hold different content, a slot may fit better than a nested instance; see Figma slots.

Every exposed nested property multiplies how many ways the parent can look. Instancer, our plugin, includes exposed nested instance properties when it builds a combination grid, with path-based names like Icon/variant so they don't clash with the parent's own properties. Keep exposed instances at the first level: deeply nested instances may not be picked up.

If you're setting up the parent from scratch, how to create a component in Figma covers the basics.