ui:ref

Marks a part of a component so that JavaScript and CSS can find it.

<button {ui:ref(name: 'addToBasket')}>Add to basket</button>

This renders:

<button data-product-card-add-to-basket="«fq7Zr2LpA1»">Add to basket</button>

The attribute is data-<component>-<part>, the convention Zag.js uses for its own parts, and its value is the root id of the component. The client finds the part with hydrator.query('addToBasket'), CSS with [data-product-card-add-to-basket]. Zag.js adds the ids the ARIA links need when the component hydrates.

Mark one of many parts

Pass a value for parts that repeat, such as accordion items or tab panels. It also renders data-value:

<div {ui:ref(name: 'item', value: item.value)}>...</div>

A part without a value can appear several times in one instance, for example two close buttons of a dialog. Read them with hydrator.queryAll().

Add data attributes

data renders its keys as data- attributes next to the part attribute:

<button {ui:ref(name: 'addToBasket', data: {sku: product.sku})}>Add to basket</button>

Give a part an id

Pass ids on the root of the component, the same prop Zag.js uses. The part with that name renders the id and the client uses the same one:

<ui:dialog.root ids="{content: 'cookie-settings'}">...</ui:dialog.root>

Set ids through ids. An id attribute written on the element is unknown to the client and Zag.js replaces it when the component hydrates. A part with a value takes no id from ids.

Attach a part to another instance

A part can belong to another instance of the same component than the template it sits in. The trigger item of a submenu is written inside the content of the parent menu, yet it is the anchor of the submenu. Pass the root id of that instance as rootId. The ids of the surrounding component do not apply to it:

<div {ui:ref(name: 'triggerItem', rootId: childId)}>Share</div>

Mark an element in the slot content of another component

Slot content is evaluated in the template of the caller, so a bare ui:ref there does not know which component it belongs to and throws an exception. Pass context with the camelCase name of the enclosing component:

<ui:combobox.root>
  <ui:combobox.content>
    <span {ui:ref(name: 'statusText', context: 'combobox')}>Searching products...</span>
  </ui:combobox.content>
</ui:combobox.root>

For markup that the client clones for every item, such as async search results, use ui:template.

Arguments

Name	Type	Description	Required	Default
`name`	string	Name of the ref	Yes	-
`asArray`	boolean	If true, the ref will be rendered as an array instead of a string of data-attributes	No	false
`data`	array	Additional data attributes to include in the ref. Associative array with key-value pairs. Each key is prefixed with "data-".	No	[]
`value`	string\|int\|float\|BackedEnum\|UnitEnum\|null\|array	Optional discriminator for multi-instance parts (e.g. accordion items, tab triggers, slider thumbs).	No	-
`rootId`	string	Root id of another instance of the same component to attach this ref to instead of the ambient one, e.g. a submenu's trigger item rendered inside its parent menu's content. The ambient component's `ids` do not apply.	No	''
`context`	string	camelCase base name of an ancestor component to attach this ref to explicitly (e.g. "fileUpload"), for hand-authored elements living in another component's slot content rather than a component's own template body. When omitted, uses whichever component is already ambiently active (the normal case for a component's own template).	No	''