2.6 Node: Component Instance (syncRef)

In the Adobe XD Scenegraph, a Component Instance represents a placed occurrence of a reusable Master Component (also known as a Symbol). These instances are not defined by their own full set of properties but rather by a reference to their master, along with any specific overrides or state changes.

The node type for a component instance is typically "syncRef".

Purpose and Role

• Reusability: Allows designers to define a UI element once (as a Master Component) and reuse it multiple times throughout the design.
• Consistency: Ensures that all instances of a component maintain a consistent base appearance and behavior, while still allowing for controlled variations.
• Maintainability: Changes made to the Master Component are automatically propagated to all its instances, simplifying design updates.
• Interactive States: Component instances can display different pre-defined states of their Master Component (e.g., "default", "hover", "disabled").

Key Properties

A syncRef node inherits Common Node Properties like id, name, and transform. Its unique and most important properties are related to its link with the master component and its specific instance variations.

Property	Type	Description	Example Value (JSON)
type	string	Typically "syncRef", indicating it's an instance synchronized with a master.	"syncRef"
ref	string	The crucial property. This is the id of the Master Component (defined in resources.symbols) to which this instance is linked.	"master-component-guid-12345"
state	object	(Optional) An object specifying which state of the Master Component this instance should display. If absent, the default state is used.	{"id": "state-guid-abc", "name": "Hover"}
state.id	string	The id of the active state within the Master Component's state definitions.	"state-guid-abc"
state.name	string	The user-defined name of the active state.	"Hover"
overrides	array	(Optional) An array of objects defining properties that are overridden specifically for this instance, differing from the Master Component.	[ {"target": "child-node-id", "text": {"rawText": "New Label"} } ]
children	array	While instances inherit their structure from the master, this array can sometimes exist, especially if the instance itself is a complex group or has overrides that alter its child structure. However, the primary source of truth for the structure is the master.	[ ... ] (Often minimal or reflecting overrides)
meta.ux.symbolId	string	Often identical or related to the ref property, reinforcing the link to the master symbol.	"master-component-guid-12345"

Relationship with Master Components (resources.symbols)

A syncRef node is intrinsically linked to a Master Component defined in the resources.symbols array (typically within resources/graphics/graphicContent.agc or a shared library).

• The syncRef.ref property directly matches the id of a Master Component in resources.symbols.
• The Master Component defines the base structure, appearance, all possible states, and default interactions.
• The syncRef instance inherits all these characteristics and can then apply specific state selections and overrides.

Overrides

The overrides array allows instances to differ from their master in specific ways without breaking the link. Common overrides include:

• Text Content: Changing the rawText of a child Text node within the component.
• Styles: Modifying fills, strokes, or effects of child Shape nodes.
• Visibility: Hiding or showing specific child layers.

Each object in the overrides array typically specifies a target (the id of the child node within the master component to be overridden) and the property to change.

JSON Example: Component Instance (syncRef)

{
  "type": "syncRef",
  "id": "component-instance-button-001",
  "name": "Submit Button (Primary)",
  "ref": "master-button-guid", // Links to a master component defined in resources.symbols
  "transform": { "a": 1, "d": 1, "tx": 50, "ty": 400 },
  "state": { // This instance is showing the "Hover" state of the master
    "id": "master-button-hover-state-guid",
    "name": "Hover"
  },
  "overrides": [
    {
      "target": "master-button-label-text-id", // ID of a text node within the master button
      "text": {
        "rawText": "Confirm Submission" // Overridden text content
      }
    }
  ],
  "meta": {
    "ux": {
      "symbolId": "master-button-guid"
    }
  }
  // 'children' might be present if structure is complex or heavily overridden
}

Interpreting syncRef nodes requires looking up their corresponding Master Component in resources.symbols to get the base definition, then applying any specified state and overrides to derive the final appearance and properties of the instance. This system is fundamental to understanding reusable elements in Adobe XD designs.