{
  "doc": {
    "id": "ui-coverage/configuration/elements",
    "title": "Elements | Cypress UI Coverage",
    "description": "The `elements` configuration allows you to uniquely identify elements in UI Coverage using custom logic.",
    "section": "ui-coverage",
    "source_path": "/llm/markdown/ui-coverage/configuration/elements.md",
    "version": "e6988a974973e9090ce70406c38cb2b9e0eac9fa",
    "updated_at": "2026-05-15T15:50:22.536Z",
    "headings": [
      {
        "id": "ui-coverage/configuration/elements#elements",
        "text": "elements",
        "level": 1
      },
      {
        "id": "ui-coverage/configuration/elements#why-use-elements-configuration",
        "text": "Why use elements configuration?",
        "level": 2
      },
      {
        "id": "ui-coverage/configuration/elements#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "ui-coverage/configuration/elements#options",
        "text": "Options",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elements#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "ui-coverage/configuration/elements#identify-elements-by-dynamic-selector-across-snapshots",
        "text": "Identify elements by dynamic selector across snapshots",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elements#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#elements-shown-in-ui-coverage",
        "text": "Elements shown in UI Coverage",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#identify-elements-with-human-readable-names",
        "text": "Identify elements with human-readable names",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elements#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#elements-shown-in-ui-coverage",
        "text": "Elements shown in UI Coverage",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#scoping-element-identification-to-shadow-dom",
        "text": "Scoping element identification to shadow DOM",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elements#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#elements-shown-in-ui-coverage",
        "text": "Elements shown in UI Coverage",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#scoping-element-identification-to-iframes",
        "text": "Scoping element identification to iframes",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elements#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#elements-shown-in-ui-coverage",
        "text": "Elements shown in UI Coverage",
        "level": 4
      }
    ]
  },
  "chunks": [
    {
      "id": "ui-coverage/configuration/elements#why-use-elements-configuration",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Why use elements configuration?",
      "heading_level": 2,
      "content_markdown": "## Why use elements configuration?\n\n*   **Handle Dynamic Attributes**: Ensure elements are consistently identified across snapshots, even when attributes change.\n*   **Ensure Unique Identification**: Use custom selectors to uniquely identify elements across snapshots that lack unique attributes or have dynamic values, avoiding misclassification.\n*   **Simplify Debugging**: Assign human-readable names to elements to make reports more interpretable and debugging easier.\n",
      "section": "ui-coverage",
      "anchors": [
        "why-use-elements-configuration"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 79
    },
    {
      "id": "ui-coverage/configuration/elements#syntax",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Syntax",
      "heading_level": 2,
      "content_markdown": "## Syntax\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": string,        \"name\": string,        \"documentScope\": [string],        \"comment\": string      }    ]  }}\n```\n\n### Options\n\nFor every element considered by UI Coverage, the first applicable rule, determined by a match with the `selector` property, is used for identification. Elements that do not match any rules are identified by the default UI Coverage [element identification rules](/llm/markdown/ui-coverage/core-concepts/element-identification.md).\n\nIf multiple elements within the same snapshot satisfy the same rule, the rule cannot uniquely identify these elements. In such cases, the rule is bypassed, and either subsequent rules or the default element identification logic are applied.\n\n| Option | Required | Default | Description |\n| --- | --- | --- | --- |\n| `selector` | Required |  | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |\n| `name` | Optional | `selector` | A human-readable name for the element, displayed in UI Coverage reports. |\n| `documentScope` | Optional |  | An array of CSS selectors that identify document hosts (iframes or shadow DOM hosts) that must be ancestors of the matched element. The selector will only match if all specified document hosts are found in the element's ancestor chain. |\n| `comment` | Optional |  | A comment describing the purpose of this element configuration. |\n",
      "section": "ui-coverage",
      "anchors": [
        "syntax"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 297
    },
    {
      "id": "ui-coverage/configuration/elements#options",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Options",
      "heading_level": 3,
      "content_markdown": "### Options\n\nFor every element considered by UI Coverage, the first applicable rule, determined by a match with the `selector` property, is used for identification. Elements that do not match any rules are identified by the default UI Coverage [element identification rules](/llm/markdown/ui-coverage/core-concepts/element-identification.md).\n\nIf multiple elements within the same snapshot satisfy the same rule, the rule cannot uniquely identify these elements. In such cases, the rule is bypassed, and either subsequent rules or the default element identification logic are applied.\n\n| Option | Required | Default | Description |\n| --- | --- | --- | --- |\n| `selector` | Required |  | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |\n| `name` | Optional | `selector` | A human-readable name for the element, displayed in UI Coverage reports. |\n| `documentScope` | Optional |  | An array of CSS selectors that identify document hosts (iframes or shadow DOM hosts) that must be ancestors of the matched element. The selector will only match if all specified document hosts are found in the element's ancestor chain. |\n| `comment` | Optional |  | A comment describing the purpose of this element configuration. |\n",
      "section": "ui-coverage",
      "anchors": [
        "options"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 269
    },
    {
      "id": "ui-coverage/configuration/elements#examples",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Examples",
      "heading_level": 2,
      "content_markdown": "## Examples\n\n### Identify elements by dynamic selector across snapshots\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#my-form [id^='dropdown']\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<!-- Snapshot 1 --><body>  <form id=\"my-form\">    <input id=\"dropdown-142\"></input>  </form></body><!-- Snapshot 2 --><body>  <form id=\"my-form\">    <input id=\"dropdown-980\"></input>  </form></body>\n```\n\n#### Elements shown in UI Coverage\n\n```\n#my-form [id^=\"dropdown\"]\n```\n\n* * *\n\n### Identify elements with human-readable names\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#ui-popover-button\",        \"name\": \"Help Popover\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <button id=\"ui-popover-button\">Help</button></body>\n```\n\n#### Elements shown in UI Coverage\n\n```\nHelp Popover\n```\n\n* * *\n\n### Scoping element identification to shadow DOM\n\nWhen you need to uniquely identify elements within a specific shadow DOM host, use the `documentScope` property to scope your selector to that document context.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#my-button\",        \"name\": \"Custom Component Button\",        \"documentScope\": [\"custom-component\"]      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <button id=\"my-button\">Button Outside Shadow DOM</button>  <custom-component>    #shadow-dom      <button id=\"my-button\">Button Inside Shadow DOM</button>  </custom-component></body>\n```\n\n#### Elements shown in UI Coverage\n\n```\n#my-button (from root document)Custom Component Button (from shadow DOM)\n```\n\nOnly the button inside the shadow DOM is identified using the custom name, while the button in the root document uses the default identification.\n\n* * *\n\n### Scoping element identification to iframes\n\nYou can also scope element identification to elements within specific iframes using `documentScope`.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#submit\",        \"name\": \"Embedded Form Submit\",        \"documentScope\": [\"#embedded-form\"]      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <button id=\"submit\">Submit (Root)</button>  <iframe id=\"embedded-form\" src=\"http://www.foo.com\">    <html>      <body>        <button id=\"submit\">Submit (Embedded)</button>      </body>    </html>  </iframe></body>\n```\n\n#### Elements shown in UI Coverage\n\n```\n#submit (from root document)Embedded Form Submit (from iframe)\n```\n\nOnly the button inside the iframe is identified using the custom name.\n",
      "section": "ui-coverage",
      "anchors": [
        "examples"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 408
    },
    {
      "id": "ui-coverage/configuration/elements#identify-elements-by-dynamic-selector-across-snapshots",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Identify elements by dynamic selector across snapshots",
      "heading_level": 3,
      "content_markdown": "### Identify elements by dynamic selector across snapshots\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#my-form [id^='dropdown']\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<!-- Snapshot 1 --><body>  <form id=\"my-form\">    <input id=\"dropdown-142\"></input>  </form></body><!-- Snapshot 2 --><body>  <form id=\"my-form\">    <input id=\"dropdown-980\"></input>  </form></body>\n```\n\n#### Elements shown in UI Coverage\n\n```\n#my-form [id^=\"dropdown\"]\n```\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "identify-elements-by-dynamic-selector-across-snapshots"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 77
    },
    {
      "id": "ui-coverage/configuration/elements#identify-elements-with-human-readable-names",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Identify elements with human-readable names",
      "heading_level": 3,
      "content_markdown": "### Identify elements with human-readable names\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#ui-popover-button\",        \"name\": \"Help Popover\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <button id=\"ui-popover-button\">Help</button></body>\n```\n\n#### Elements shown in UI Coverage\n\n```\nHelp Popover\n```\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "identify-elements-with-human-readable-names"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 59
    },
    {
      "id": "ui-coverage/configuration/elements#scoping-element-identification-to-shadow-dom",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Scoping element identification to shadow DOM",
      "heading_level": 3,
      "content_markdown": "### Scoping element identification to shadow DOM\n\nWhen you need to uniquely identify elements within a specific shadow DOM host, use the `documentScope` property to scope your selector to that document context.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#my-button\",        \"name\": \"Custom Component Button\",        \"documentScope\": [\"custom-component\"]      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <button id=\"my-button\">Button Outside Shadow DOM</button>  <custom-component>    #shadow-dom      <button id=\"my-button\">Button Inside Shadow DOM</button>  </custom-component></body>\n```\n\n#### Elements shown in UI Coverage\n\n```\n#my-button (from root document)Custom Component Button (from shadow DOM)\n```\n\nOnly the button inside the shadow DOM is identified using the custom name, while the button in the root document uses the default identification.\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "scoping-element-identification-to-shadow-dom"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 153
    },
    {
      "id": "ui-coverage/configuration/elements#elements-shown-in-ui-coverage",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Elements shown in UI Coverage",
      "heading_level": 4,
      "content_markdown": "#### Elements shown in UI Coverage\n\n```\n#my-button (from root document)Custom Component Button (from shadow DOM)\n```\n\nOnly the button inside the shadow DOM is identified using the custom name, while the button in the root document uses the default identification.\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "elements-shown-in-ui-coverage"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 59
    },
    {
      "id": "ui-coverage/configuration/elements#scoping-element-identification-to-iframes",
      "doc_id": "ui-coverage/configuration/elements",
      "heading": "Scoping element identification to iframes",
      "heading_level": 3,
      "content_markdown": "### Scoping element identification to iframes\n\nYou can also scope element identification to elements within specific iframes using `documentScope`.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#submit\",        \"name\": \"Embedded Form Submit\",        \"documentScope\": [\"#embedded-form\"]      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <button id=\"submit\">Submit (Root)</button>  <iframe id=\"embedded-form\" src=\"http://www.foo.com\">    <html>      <body>        <button id=\"submit\">Submit (Embedded)</button>      </body>    </html>  </iframe></body>\n```\n\n#### Elements shown in UI Coverage\n\n```\n#submit (from root document)Embedded Form Submit (from iframe)\n```\n\nOnly the button inside the iframe is identified using the custom name.\n",
      "section": "ui-coverage",
      "anchors": [
        "scoping-element-identification-to-iframes"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elements.json",
      "token_estimate": 116
    }
  ]
}