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.