Skip to main content
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 — to position tooltips relative to an element, trigger on element visibility, or listen for clicks/hovers.
  • Tours — each step in a Tour can target one or more elements.
  • Tooltips — always anchored to a specific element.
  • 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

PropertyTypeDescription
idIDThe Chameleon ID
created_attimestampWhen this happened or when this was added to the Database
updated_attimestampThe last time any property was updated
selectorstringThe full CSS / JavaScript selector to this element
descriptionstringA human-readable description of the selected element
usearray<string>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
pathstringA complete CSS Path from the body down to the element
tagstringThe HTML tag name of the element (e.g., div, a, button).
textstringThe visible text content of the element.
attr_idstringThe value of the element’s id attribute, if present.
attr_classstringThe value(s) of the element’s class attribute, typically space-separated.
attr_hrefstringThe value of the href attribute (used in links, anchors, etc.).
attr_titlestringThe value of the title attribute, often used for tooltips.
attr_typestringThe value of the type attribute (e.g., text, password, button).
attr_namestringThe value of the name attribute, often used in form controls.
aritystringRepresents the number of child nodes or arguments for the element.
shadow_selectorstringA selector path inside a shadow DOM, if the element resides in one.
path_indexstringIndex-based representation of the element’s location in the DOM hierarchy.
attr_datastringCustom data-* attribute value(s) associated with the element.
attr_aria_labelledbystringValue of the aria-labelledby attribute (points to element IDs).
attr_aria_labelstringValue of the aria-label attribute, providing accessibility text.

​
Example element JSON

{
  "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 or Tour with the appropriate expand parameter. For example, a Step’s trigger_element and position_element fields are Element objects: 
{
  "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 for all element-related fields on a Step.