Identify matching objects

If you're using UI3, Figma's new design, some parts of this article might not match what you see in the product today. We appreciate your patience while we make updates. Learn more about Figma’s redesign →

Matching objects are identical objects that exist across more than one frame. For example, many app designs use an identical header across the top of each frame.

Use matching objects to save time when selecting, editing, and prototyping.

Three different frames, depicting checkout cart designs. Across the top of each frame is the same header with a navigation menu and a checkout cart icon.

Matching objects are used with:

Smart animate: Create advanced animations between matching objects when prototyping
Multi-edit: Edit objects in bulk
State management: When prototyping, share the state of interactive components, frames with scroll, and videos when navigating between frames with matching objects
Matching interactions: Select and edit prototyping interactions on matching objects in bulk

In order for two objects to be considered matching, they must:

Matching object requirements

Figma uses the following terms to help define matching object requirements:

Parent objects: Objects such as frames, components, and groups, that contain other objects.
- Grandparent objects are objects that contain the parent object. Ancestors are any other objects in the hierarchy that contain child, parent, or grandparent objects.
Children, or child objects: Objects that are contained within a parent.
Top-level frames: Frames placed directly on the canvas. They do not have any parent objects.

Learn more about parent, child and sibling relationships →

Note: Top-level frames can be matching objects, but only for smart animate or state management. You cannot use multi-edit or select matching interactions on top-level frames.

Objects in sections can only match with other objects within that section.

Layer names

Objects must have the same layer name.

There are two exceptions to this rule:

Text layers

Text layers don’t always require identical layer names. When you create a text layer, the name of the layer will reflect the content of the text itself. You have the option to rename the text layer.

If the text layers were explicitly named or renamed from the Layers panel, the names must match.
If the text layers were implicitly named based on the text content, their text styles must match. If there are multiple matching text objects, the best match will be selected based on the x and y coordinates of the text layer in the frame.

Top-level frames

In order for top-level frames to be considered matching, one of the following must be true:

The frame names match.
The frame names have a common prefix, followed by a forward slash. For example, Checkout / Empty and Checkout / Complete match.

In the first example, there is a frame with a rectangle object named 'rectangle'. A second frame has a rectangle object also named 'rectangle', so the two rectangle objects match. In the second example, there is a frame with a rectangle object name 'rectangle'. A second frame has a rectangle object named 'shape'. The two rectangle objects do not match.

Parent frames

All parent and ancestor frames of the objects must have matching names.

In the first example, there is an object that sits in a parent frame named 'parent'. A second object also has an object that sits in a parent frame named 'parent'. The objects match. In the second example, there is an object that sits in a parent frame named 'parent'. A second object also sits in a parent frame that is named 'mother'. The objects do not match.

Note: Top-level frames and variant names in a component set do not need to match.

Layer hierarchy

In order to be considered matching, objects must have the same position in layer hierarchy across top-level frames. For example, an object that has a parent and grandparent layer in one frame must also have a parent and grandparent layer in the second frame.

Tip: When all requirements match, and there are two or more objects with the same name in a frame, the index of the object within the parent frame is used to determine which one matches.

Two identical frames, each with two objects. Object A matches with Object B in the second frame. Even though Object A visually appears above Object B, they have the same index from the left Layer panel.

To highlight matching objects on the same page:

Click to select an object.
Hold Shift to highlight all matching objects in light blue.

Alternatively, you can identify matching objects from the Prototype tab.

Open the Prototype tab in the right sidebar.
Hover over an object or layer in the canvas.

Figma will highlight the matching object in any other frames it exists in.