Instance Swap Properties: Control Nested Components

WHY IT EXISTS Instance swap properties were created to solve the problem of managing nested components within larger, more complex ones. Without them, designers had to manually find and replace nested instances, risking detachment from the main component or incorrect overrides, making the design system fragile and hard to use.

THE MENTAL MODEL Think of an instance swap property as a designated, swappable slot in a template. It's like a picture frame where you can easily change the photo. You define the frame (the slot for the nested component) and can even suggest a collection of recommended photos (preferred instances) to put inside it.

HOW IT WORKS To create one, you select a nested component layer within a main component. In the properties panel, you create an 'Instance Swap' property. You can then optionally select a set of 'preferred instances' from your libraries, such as your approved icon set. Anyone using an instance of your main component will now see a simple dropdown in their properties panel to swap out that nested component.

WHEN TO USE IT Use this for any component that contains another component you want users to be able to change. Common examples include: icons inside buttons, avatars in user cards, status indicators in table rows, or logos in a header. It is essential for building flexible and scalable design systems where parts are interchangeable.

WHEN NOT TO USE IT Don't use an instance swap for simple visibility changes; a Boolean property (show/hide) is better for that. It's also not the right tool for changing fundamental variations of the component itself, like its size or color state; that's what Variant properties are for.

ONE CANONICAL EXAMPLE A 'Button' component contains a nested 'Icon' component. To allow designers to change the icon from 'plus-icon' to 'trash-icon', you select the icon layer within the main Button component and create an instance swap property named 'Icon'. You set the preferred values to your library's icon set. Now, a designer using the button can select a new icon from a dropdown in the right-hand panel, instead of manually digging into layers.