--- id: ui-coverage/configuration/elementgroups title: Element Groups | Cypress UI Coverage description: >- The `elementGroups` configuration allows you to group elements in UI Coverage using custom logic. section: ui-coverage source_path: docs/ui-coverage/configuration/elementgroups.mdx version: 7ada28c0cd90e81cf56fd3fc73de6e6d45c16de6 updated_at: '2026-05-13T21:55:41.935Z' --- # elementGroups UI Coverage provides logic to automatically [group](/llm/markdown/ui-coverage/core-concepts/element-grouping.md) elements based on their structure in the DOM. However, there are scenarios where you may want to customize these groups to better align with your application's functionality or testing requirements. The `elementGroups` configuration allows you to define custom logic for grouping elements, improving coverage clarity and simplifying analysis. ## Why use element groups? * **Improve Grouping Accuracy**: Ensure elements with shared attributes but different roles are correctly grouped, avoiding misclassification. * **Simplify Test Coverage Reports**: Grouping similar elements, like navigation buttons or list items, reduces clutter in reports and provides a more concise view of test coverage. * **Highlight Key Areas**: Use meaningful group names to draw attention to critical application areas, such as form controls. * **Streamline Dynamic Elements**: Consolidate dynamic or repeated elements, such as items in a carousel or list, into a single logical group. ## Syntax ``` { "uiCoverage": { "elementGroups": [ { "selector": string, "name": string, "documentScope": [string], "comment": string } ] }} ``` ### Options For every element considered by UI Coverage, the first `elementGroup` rule for which the `selector` property matches the element is used to group the element. Elements that do not match any rules are grouped by the default UI Coverage [element grouping rules](/llm/markdown/ui-coverage/core-concepts/element-grouping.md). | Option | Required | Default | Description | | --- | --- | --- | --- | | `selector` | Required | | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. | | `name` | Optional | `selector` | A human-readable name for the group, displayed in UI Coverage reports. | | `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. | | `comment` | Optional | | A comment describing the purpose of this element group configuration. | ## Examples ### Groups elements by selector #### Config ``` { "uiCoverage": { "elementGroups": [ { "selector": "[data-cy^='item-']" } ] }} ``` #### HTML ``` ``` #### Elements shown in UI ``` [data-cy^='item-'] (3 instances) ``` * * * ### Groups all elements in a container #### Config ``` { "uiCoverage": { "elementGroups": [ { "selector": "#calendar button" } ] }} ``` #### HTML ```

``` #### Elements shown in UI ``` #calendar button (3 instances) ``` * * * ### Groups form controls with labels #### Config ``` { "uiCoverage": { "elementGroups": [ { "selector": "input[name='animal'], label:has(input[name='animal'])", "name": "Animal Option" } ] }} ``` #### HTML ``` ``` #### Elements shown in UI ``` Animal Option (4 instances) ``` ### Groups dynamic elements #### Config ``` { "uiCoverage": { "elementGroups": [ { "selector": "[id^='product']" } ] }} ``` #### HTML ``` ``` #### Elements shown in UI ``` [id^='product'] (3 instances) ``` ### Giving groups custom names Sometimes you may want to group elements by a common attribute but give the group a more descriptive name. In the following example, we group buttons with IDs starting with `listbox-button-` and name the group `Add Button`. #### Config ``` { "uiCoverage": { "elementGroups": [ { "selector": "[id^='listbox-button-']", "name": "Add Button" } ] }} ``` #### HTML ``` ``` #### Elements shown in UI ``` Add Button (4 instances) ``` * * * ### Grouping elements within shadow DOM When you need to group elements within a specific shadow DOM host, use the `documentScope` property to scope your selector to that document context. #### Config ``` { "uiCoverage": { "elementGroups": [ { "selector": "button", "name": "Shadow DOM Buttons", "documentScope": ["custom-component"] } ] }} ``` #### HTML ``` #shadow-dom ``` #### Elements shown in UI ``` #root-buttonShadow DOM Buttons (2 instances) ``` Only the buttons inside the shadow DOM are grouped together, while the root button remains separate. * * * ### Grouping elements within iframes You can also scope element grouping to elements within specific iframes using `documentScope`. #### Config ``` { "uiCoverage": { "elementGroups": [ { "selector": "[data-action]", "name": "Embedded Actions", "documentScope": ["#embedded-widget"] } ] }} ``` #### HTML ``` ``` #### Elements shown in UI ``` [data-action="save"] (from root document)Embedded Actions (2 instances) ``` Only the buttons inside the iframe are grouped together.