Components

What a component is

A component has one main component, the original, and any number of instances, the copies you place in your designs. Edit the main and every instance changes with it. Each instance can still have its own text, colours and sizes where it needs them.

Make a component when the same part appears on more than one screen, or when you want the rest of your team to use it the same way. For a one-off layout, plain frames are quicker.

Make a component

1. Select one layer: usually a frame that holds the whole part.
2. Right-click it on the board and choose Create component (or press ⌥⌘K). For a shape or a picture, the Create component button beside its name at the top of the right panel does the same.

The layer is now the main component. Components are drawn in purple: in the layers panel, in the inspector and on the board, so you can tell them from ordinary frames at a glance.

Main and instances

There are a few ways to get an instance of a main component:

• Right-click the main and choose Create instance. The instance lands beside it.
• Right-click the main and choose Duplicate, or hold ⌥ and drag it. A copy of a main is always an instance, never a second main.
• Place it from the Assets tab (see Place from Assets).

Select an instance and the inspector's Instance section says which component it is. Its menu (the Instance actions button) has Go to main component, Reset instance and Detach instance; the same three are in the right-click menu. Select a layer inside an instance and a purple line at the top of the inspector says In and the component's name, with Go to main, Reset and Detach.

Change an instance

You can change anything on an instance: its words, fills, strokes, sizes, and which layers show. Each change you make there is an override: that value belongs to the instance from then on. Later edits to the main still reach the instance, except for the values it has made its own.

Where an instance sits, and whether it is locked, are always its own: moving the main never moves its instances.

Reset and detach

• Reset instance drops every override, so the instance matches its main again.
• Detach instance turns the instance back into ordinary layers. It keeps how it looks but no longer follows the main.
• Go to main component selects the main and zooms to it, on whichever page it is.

Variants

Variants are versions of one component: a button that is primary or secondary, small or large, resting or hovered. They live together in a component set, drawn with a dashed purple outline, and each instance can switch between them.

• Combine as variants: select two or more main components that sit side by side (in the same frame, or all on the board), right-click and choose it. Names written as Size=Large, State=Hover become the values of each property. A name like Button/Primary/Large makes a set called Button with a property for each part after the first.
• Add variant: right-click a main or a set and choose it, or select the set (or one of its variants) and click the purple + under it. A main that isn't in a set yet becomes a set of one.

Select one variant and the inspector shows Current variant: its value for each property. Type a new value or pick one the set already uses. Under a selected set, the board says how many variants it holds.

Properties

Properties are the settings an instance offers, so whoever uses the component changes what it is meant to change and nothing else. Select a main or a set, find Properties in the inspector and click + (Create property). There are four kinds:

Text, Boolean and Instance swap properties each have a Default, which new instances start with. Double-click a property's name to rename it; the − beside it deletes it.

Tie a layer to a property

A property does nothing until a layer inside the main is tied to it:

1. Select the layer inside the main component.
2. Click the purple diamond in the inspector: in the Text section's heading for its words, the Appearance heading for whether it shows, or the Instance section for a nested instance.
3. Pick an existing property of that kind, or Create property to make one from the layer.

Once tied, the property's name shows in a purple pill in place of the diamond. Click it to tie the layer to another property, or choose Detach property.

Nested instances

When a main holds instances of other components, its Properties list them under Nested instances shown on instances. Tick one and every instance of the main shows that nested instance's properties too, under its name, so they can be set without digging into the layers.

Swap an instance

To make an instance a different component, select it and pick another component from the menu at the top of its Instance section. It lists the components made in this file; a set places its default variant. Variant properties are listed underneath: choose a value and the instance switches to that variant, or to the closest one if no variant has exactly those values.

Place from Assets

The Assets tab, beside Layers at the top of the left panel, holds every component you can place: Created in this file first, then each library in your workspace under its own name. A number beside a component says how many variants it has.

• Type in Search assets to find one by name or by a variant's name.
• Click a component to place an instance in the middle of your view.
• Drag it onto the board to place it where you drop it, inside the frame under the pointer.

Libraries

A library is a file whose components the rest of your workspace can use. Keep your buttons, cards and icons in one file, publish it, and every other file in the workspace can place them from Assets. When you improve a component, you publish the change and the other files take it when they are ready.

Publish a library

1. Make the components in the file.
2. In the Assets tab, click the Local variables button beside the design system picker. A dock opens under the board.
3. Open its Library tab and, under This file, choose Publish as a library.

The line then reads Published as a library, with its version and how many components it has. Edits to the main components stay in this file until you choose Publish changes, which makes a new version. Unpublish takes it out of the workspace's libraries: files that already placed its components keep them as they are, and get no more updates from it.

The same tab lists Libraries in this workspace, each with its number of components and its version. Their components are in Assets.

A design system can have a library too: its logos and parts, listed first in Assets, under the system's name, in every file that uses it.

Take updates

When a library publishes a newer version of a component you placed, the Assets tab shows a line such as 1 library update with Review. It opens Updates in the Library tab, which lists each component waiting and how many of your instances use it.

Choose Update (or Update all and the number, when there are several) to bring them up to date in one step. A message says how many instances were updated, with Undo if you change your mind. Your overrides are kept, and so is anything you put inside an instance yourself.

On an instance from a library, Go to main component opens the library's file on its original. Reset instance puts it back to the library's component as published now.

Who can use a library

• Anyone who can edit a file can publish it as a library, or publish its changes.
• Members of the workspace can place from its libraries, as long as they can open the library's file. A library whose file is set to Invite only is only offered to its owner and the workspace's owners. See Sharing.
• People invited to one file from outside the workspace don't see the workspace's libraries.

Components and agents

Agents can make and use components too. With Build with components on, a part that repeats across screens, like a nav, becomes one component, so you edit it once; agents take longer to draw that way. It is off by default. Turn it on for every file under Settings → Agents, or for one file from Agents in this file, the button beside the people at the top right of the editor. See Working with agents.