> ## Documentation Index
> Fetch the complete documentation index at: https://developers.chameleon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Elements
> Elements define which HTML element an experience will be anchored to, positioned next to, triggered from, or dismissed when clicked.
Elements are the bridge between Chameleon Experiences and your product's UI. They describe **how to find a specific HTML element** on the page using a combination of CSS selectors, attributes, and DOM path information.
Elements are used by:
* **[Steps](/apis/steps)** — to position tooltips relative to an element, trigger on element visibility, or listen for clicks/hovers.
* **[Tours](/apis/tours)** — each step in a Tour can target one or more elements.
* **[Tooltips](/apis/tooltips)** — always anchored to a specific element.
* **[Buttons](/apis/buttons)** — can trigger a click on a target element.
> Elements are managed automatically by the Chameleon Builder when you visually select elements in your product. The API provides read access to inspect element configurations.
***
## Schema
| Property | Type | Description |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | ID | The Chameleon ID |
| `created_at` | timestamp | When this happened or when this was added to the Database |
| `updated_at` | timestamp | The last time any property was updated |
| `selector` | string | The full CSS / JavaScript selector to this element |
| `description` | string | A human-readable description of the selected element |
| `use` | array\ | A list of the attributes of the element that are used to build `selector`. Any of: `selector`, `path`, `tag`, `text`, `attr_id`, `attr_class`, `attr_href`, `attr_title`, `attr_type`, `attr_name`, `arity`, `shadow_selector`, `path_index`, `attr_data`, `attr_aria_labelledby`, or `attr_aria_label`. If `selector` is included then the element will be selected ONLY by the `selector` |
| `path` | string | A complete CSS Path from the body down to the element |
| `tag` | string | The HTML tag name of the element (e.g., `div`, `a`, `button`). |
| `text` | string | The visible text content of the element. |
| `attr_id` | string | The value of the element's `id` attribute, if present. |
| `attr_class` | string | The value(s) of the element's `class` attribute, typically space-separated. |
| `attr_href` | string | The value of the `href` attribute (used in links, anchors, etc.). |
| `attr_title` | string | The value of the `title` attribute, often used for tooltips. |
| `attr_type` | string | The value of the `type` attribute (e.g., `text`, `password`, `button`). |
| `attr_name` | string | The value of the `name` attribute, often used in form controls. |
| `arity` | string | Represents the number of child nodes or arguments for the element. |
| `shadow_selector` | string | A selector path inside a shadow DOM, if the element resides in one. |
| `path_index` | string | Index-based representation of the element's location in the DOM hierarchy. |
| `attr_data` | string | Custom `data-*` attribute value(s) associated with the element. |
| `attr_aria_labelledby` | string | Value of the `aria-labelledby` attribute (points to element IDs). |
| `attr_aria_label` | string | Value of the `aria-label` attribute, providing accessibility text. |
#### Example element JSON
```json theme={null}
{
"id": "5f3c4232c712de665632a7e1",
"created_at": "2029-04-07T12:18:00Z",
"updated_at": "2029-04-07T12:18:00Z",
"selector": "#onboarding-btn",
"description": "Onboarding start button",
"use": ["attr_id"],
"path": "body > div.app > header > button#onboarding-btn",
"tag": "button",
"text": "Get Started",
"attr_id": "onboarding-btn",
"attr_class": "btn btn-primary",
"attr_type": "button"
}
```
### How element selection works
Chameleon uses the `use` array to determine which attributes to combine when building the runtime selector. This enables resilient element targeting even when your UI changes:
* **`selector` only** — When `use` includes `selector`, the raw CSS/JS selector is used directly. Best for stable, unique selectors like `#my-button`.
* **Combined attributes** — When `use` includes multiple attributes (e.g., `["tag", "text", "attr_class"]`), Chameleon combines them to build a more resilient selector that can tolerate minor DOM changes.
* **Shadow DOM** — When your element is inside a Web Component's shadow DOM, the `shadow_selector` provides the path within the shadow root.
***
## Elements in context
Elements appear as embedded objects within other resources. They are not listed or retrieved independently — instead, they are included when you retrieve a [Step](/apis/steps) or [Tour](/apis/tours) with the appropriate `expand` parameter.
For example, a Step's `trigger_element` and `position_element` fields are Element objects:
```json theme={null}
{
"step": {
"id": "5f3c4232c712de665632a8f1",
"step_trigger": "element_match",
"position_type": "snap_to_element",
"trigger_element": {
"id": "5f3c4232c712de665632a7e1",
"selector": "#onboarding-btn",
"tag": "button",
"text": "Get Started",
"use": ["attr_id"]
},
"position_element": {
"id": "5f3c4232c712de665632a7e2",
"selector": ".dashboard-sidebar .nav-item:first-child",
"tag": "li",
"use": ["selector"]
}
}
}
```
See [Steps](/apis/steps) for all element-related fields on a Step.