ui:ref

Generates a reference to a part of a component.

This is used to mark parts of a component for JavaScript interaction or styling. It generates the element id (using a deterministic formula based on component name, root ID and part name) along with data-scope and data-part attributes.

Example

<div {ui:ref(name: 'button')}">Click me</div>

This will generate:

<div id="my-component:«uniqueRootId»:button" data-scope="my-component" data-part="button">Click me</div>

For multi-instance parts (e.g. accordion items, tab panels) pass a value: discriminator:

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

You can also pass additional data attributes:

<div {ui:ref(name: 'button', data: { action: 'submit' })}">Click me</div>

This will generate:

<div id="..." data-scope="my-component" data-part="button" data-action="submit">Click me</div>

A component's slot content (the markup a consumer writes between its opening/closing tags) is always evaluated against the calling rendering context, not the component's own internal one - so a bare ui:ref written directly inside such slot content doesn't, by default, know which component (or rootId) it belongs to, and throws. Pass context to attach it explicitly to a named ancestor component instead (resolved the same way ui:template's own context argument is - it threads correctly through slot-content nesting, unlike the ambient component/context variables this ViewHelper otherwise reads):

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

Use ui:template instead when the content's real data doesn't exist yet at server-render time and needs cloning client-side per instance (e.g. async search results) - context here is for hand-authored elements that render immediately, once, and never get cloned.

Arguments