Customize UI element naming for user interactions

  • Latest Dynatrace
  • How-to guide
  • Published Mar 20, 2026

Early Adopter

Each user interaction includes details about the UI element involved. For web frontends, these are HTML elements. Their names are used in user interaction descriptions in the Users & Sessions Users & Sessions app. This page explains how UI element naming works and how you can customize it.

Default detection of the UI element name

The RUM JavaScript detects a name for the UI element and stores it in the ui_element.detected_name field on the user interaction. To do this, it checks attributes in the following order and uses the first available match:

  1. aria-label
  2. title
  3. name (for example on the elements input, form, and iframe)
  4. data-testid (a widely used custom attribute for identifying a DOM node during testing)
  5. placeholder (for input elements)
  6. id

Unless you define a custom name, Dynatrace uses ui_element.detected_name to determine the ui_element.name field used in user interaction descriptions in the Users & Sessions Users & Sessions app. The name is limited to 32 characters. For specifications of both fields, see User interactions in the Semantic Dictionary.

Define a custom name

If the name detected by default does not suit your requirements, you can customize it. The RUM JavaScript stores custom names on the user interaction in the ui_element.custom_name field, alongside the standard ui_element.detected_name field. Dynatrace then uses ui_element.custom_name instead of ui_element.detected_name to determine ui_element.name.

Define a custom name for a specific element

To set a custom name for a specific element, add the HTML attribute data-dt-name. Empty or whitespace-only values for data-dt-name are ignored.

<!-- Button gets both ui_element.detected_name="Submit" and ui_element.custom_name="Checkout Button" -->
<button name="Submit" data-dt-name="Checkout Button">Submit</button>

Handle icon buttons correctly

Icon buttons are buttons where a nested icon element (for example, svg) is the visible part and often receives the click. If you set data-dt-name only on the button, the custom name is used only when the button element itself is clicked. If the click lands on the nested icon, the custom name isn't captured.

<!-- Button click: ui_element.custom_name="Delete Item"; icon click: no custom name -->
<button data-dt-name="Delete Item">
  <svg><!-- trash icon --></svg>
</button>

To cover both the button and its icon, use data-dt-children-name as described in the next section.

Define a custom name for an element and its children

Add the data-dt-children-name attribute to define a custom name for the element itself and for all descendant elements. This lets you:

  • Label all items in a list or grid
  • Name all controls in a toolbar or form section
  • Apply consistent naming to dynamic content
  • Name container elements that represent business entities

Empty or whitespace-only values for data-dt-children-name are ignored.

Examples
<!-- Toolbar div itself gets ui_element.custom_name="Toolbar Action" -->
<!-- All buttons inside also get ui_element.custom_name="Toolbar Action" -->
<div class="toolbar" data-dt-children-name="Toolbar Action">
  <button>✂️</button>  <!-- ui_element.custom_name="Toolbar Action" -->
  <button>📋</button>  <!-- ui_element.custom_name="Toolbar Action" -->
  <button>🔍</button>  <!-- ui_element.custom_name="Toolbar Action" -->
</div>


<!-- Fieldset gets ui_element.custom_name="Billing Field" -->
<!-- All inputs inherit the same custom name -->
<fieldset data-dt-children-name="Billing Field">
  <input type="text" name="address">    <!-- ui_element.detected_name="address", ui_element.custom_name="Billing Field" -->
  <input type="text" name="city">       <!-- ui_element.detected_name="city", ui_element.custom_name="Billing Field" -->
  <input type="text" name="zip">        <!-- ui_element.detected_name="zip", ui_element.custom_name="Billing Field" -->
</fieldset>


<!-- Card container and its content both get meaningful ui_element names -->
<div class="card" data-dt-children-name="Product Card">
  <!-- The card div itself has ui_element.custom_name="Product Card" -->
  <img src="product.jpg">   <!-- ui_element.custom_name="Product Card" -->
  <h3>Product Title</h3>     <!-- ui_element.custom_name="Product Card" -->
  <button>Add to Cart</button> <!-- ui_element.custom_name="Product Card" -->
</div>

Combine naming attributes

You can combine data-dt-name and data-dt-children-name. In this case, follow these best practices and keep the inheritance rules in mind.

Best practices

  • Use data-dt-name for specific, unique elements that need individual identification.
  • Use data-dt-children-name for groups where the container and/or its children share the same business context.
  • Combine both attributes when a container needs its own name but children need a different shared name: 
    <div data-dt-name="Navigation Bar" data-dt-children-name="Nav Item">
      <!-- Container: ui_element.custom_name="Navigation Bar" -->
      <a href="/home">Home</a>     <!-- ui_element.custom_name="Nav Item" -->
      <a href="/products">Shop</a> <!-- ui_element.custom_name="Nav Item" -->
    </div>

Inheritance rules

An element's custom name is determined in the following order of precedence:

  1. The element's own data-dt-name always takes precedence.
  2. The element's own data-dt-children-name is used if no data-dt-name exists.
  3. The closest ancestor's data-dt-children-name is used if the element itself has neither attribute.
Examples
  <!-- This div has ui_element.custom_name="Card" (uses its own data-dt-children-name) -->
<div data-dt-children-name="Card">


  <!-- This div has ui_element.custom_name="Card Action" (uses its own data-dt-children-name) -->
  <div data-dt-children-name="Card Action">
    <button>Edit</button>                     <!-- ui_element.custom_name="Card Action" (inherits) -->
    <button data-dt-name="Save">Save</button> <!-- ui_element.custom_name="Save" (own data-dt-name wins) -->
  </div>


  <p>Card content</p>                         <!-- ui_element.custom_name="Card" (inherits from parent) -->
</div>


<!-- This div has ui_element.custom_name="Dashboard Widget" -->
<div data-dt-children-name="Dashboard Widget">


  <!-- ui_element.custom_name="Widget Header" (data-dt-name wins over inheritance) -->
  <header data-dt-name="Widget Header">
    <h2>Sales</h2>  <!-- ui_element.custom_name="Dashboard Widget" (inherits from grandparent) -->
  </header>


  <!-- This div has ui_element.custom_name="Chart Container" (uses its own data-dt-children-name) -->
  <div data-dt-children-name="Chart Container">
    <canvas>Chart</canvas>  <!-- ui_element.custom_name="Chart Container" (inherits from parent) -->
  </div>


  <footer>
    <button>Refresh</button>  <!-- ui_element.custom_name="Dashboard Widget" (inherits from ancestor) -->
  </footer>
</div>
Related tags
Digital Experience