elementFilters
The elementFilters property allows you to specify selectors for elements that should be excluded from reports.
Why use element filters?​
- Ignoring 3rd Party Components: Libraries or widgets that are not part of your application logic may be excluded from reports.
- Streamlining Reports: Reducing noise by filtering out non-essential elements makes reports more actionable.
Syntax​
Note: setting elementFilters impacts both Accessibility and UI Coverage
reports if set at the root of the configuration. Nesting this property under an accessibility or uiCoverage key is
supported, if you need to split them up.
{
"elementFilters": [
{
"selector": string,
"include": boolean,
"documentScope": [string],
"comment": string
}
]
}
Options​
The first elementFilters rule for which the selector property matches the element is used to either include or exclude the element based on the include value. Elements that do not match any rules are included by default.
| Option | Required | Default | Description |
|---|---|---|---|
selector | Required | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. | |
include | Optional | true | A boolean indicating whether the matched elements should be included in the report. |
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 filter rule. |
Examples​
Excluding a specific element​
Config​
{
"elementFilters": [
{
"selector": "#button-2",
"include": false,
"comment": "Exclude test-only button from reports"
}
]
}
HTML​
<body>
<button id="button-1">Included</button>
<button id="button-2">Excluded</button>
</body>
Elements shown in UI​
#button-1
Excluding all elements in a container​
Config​
{
"elementFilters": [
{
"selector": "footer *",
"include": false
}
]
}
HTML​
<body>
<main>
<button id="start">Included</button>
</main>
<footer>
<a href="#">Excluded</a>
</footer>
</body>
Elements shown in UI​
#start
Including only elements in a specific container​
Config​
{
"elementFilters": [
{
"selector": "#form *",
"include": true
},
{
"selector": "*",
"include": false
}
]
}
HTML​
<body>
<form id="form">
<input id="name" />
</form>
<footer>
<a href="#">Excluded</a>
</footer>
</body>
Elements shown in UI​
#name
Excluding Elements by Attribute​
Config​
{
"elementFilters": [
{
"selector": "[data-role='decorative']",
"include": false
}
]
}
<body>
<button data-role="decorative">
<img src="icon.png" />
</button>
<button data-role="primary">
View
</button>
</body>
Elements shown in UI​
[data-role="primary"]
Excluding dynamic elements by pattern​
Config​
{
"elementFilters": [
{
"selector": "[class^='auth']",
"include": false
}
]
}
HTML​
<body>
<button class="cancel">Cancel</button>
<button class="auth908283794">Login</button>
</body>
Elements shown in UI​
.cancel
Scoping selectors to shadow DOM​
When you need to filter elements within a specific shadow DOM host, use the documentScope property to scope your selector to that document context.
Config​
{
"elementFilters": [
{
"selector": "#my-button",
"include": false,
"documentScope": ["custom-component"]
}
]
}
HTML​
<body>
<button id="my-button">Button Outside Shadow DOM - Important</button>
<custom-component>
#shadow-dom
<button id="my-button">Button Inside Shadow DOM - Not Important</button>
</custom-component>
</body>
Elements shown in UI​
#my-button (from root document)
Only the button inside the shadow DOM is filtered, while the button in the root document remains in the report.
Scoping selectors to iframes​
You can also scope selectors to elements within specific iframes using documentScope.
Config​
{
"elementFilters": [
{
"selector": "#my-button",
"include": false,
"documentScope": ["#my-iframe"]
}
]
}
HTML​
<body>
<button id="my-button">Button Outside Iframe - Important</button>
<iframe src="http://www.foo.com" id="my-iframe">
<html>
<body>
<button id="my-button">Button Inside Iframe - Not Important</button>
</body>
</html>
</iframe>
</body>
Elements shown in UI​
#my-button (from root document)
Only the button inside the iframe is filtered.
Scoping to nested documents​
You can chain multiple document hosts in the documentScope array to target elements within nested documents (e.g., an iframe containing a shadow DOM component).
Config​
{
"elementFilters": [
{
"selector": "#my-button",
"include": false,
"documentScope": ["iframe", "custom-component"]
}
]
}
HTML​
<body>
<button id="my-button">Button Outside Iframe - Important</button>
<iframe src="http://www.foo.com">
<html>
<body>
<button id="my-button">Button Inside Iframe - Not Important</button>
<custom-component>
#shadow-dom
<button id="my-button">Button Inside Shadow DOM - Not Important</button>
</custom-component>
</body>
</html>
</iframe>
</body>
Elements shown in UI​
#my-button (from root document)
#my-button (from iframe)
Only the button inside the shadow DOM (which is nested within the iframe) is filtered.
Filtering all elements within a document scope​
You can use a wildcard selector with documentScope to filter all elements within a specific document host.
Config​
{
"elementFilters": [
{
"selector": "*",
"include": false,
"documentScope": ["external-component"]
}
]
}
HTML​
<body>
<button id="important">Important Button</button>
<external-component>
#shadow-dom
<button id="unimportant-1">Unimportant</button>
<input id="unimportant-2" />
<a href="#" id="unimportant-3">Link</a>
</external-component>
</body>
Elements shown in UI​
#important
All elements within the external-component shadow DOM are filtered from the report.
Excluding disabled elements​
UI Coverage highlights disabled elements by default to reveal potential untested paths in your app, in case those elements become enabled later. If needed, you can exclude them from the report using the elementFilters configuration.
Config​
{
"elementFilters": [
{
"selector": "[disabled]",
"include": false
}
]
}
HTML​
<body>
<button data-cy='cancel'>Cancel</button>
<button disabled data-cy='submit'>Submit</button>
</body>
Elements shown in UI​
[data-cy='cancel']