Check Options
Table of Contents
How Checks Work
Rules in axe-core are made up of one or more individual checks that dictate how the rule works. Each check is typically designed to look for a specific requirement and report back its findings to the rule.
For example, the rule image-alt uses the checks has-alt, aria-label, aria-labelledby, and non-empty-title to determine if the image has an accessible name from an alt, aria-label, aria-labelledby, or title attribute (respectively).
Many checks allow you to change how they work through options properties. These options can be found in the checks metadata file.
For example, the check has-lang takes an attributes option which dictates which attributes to check for a lang value.
To customize a check's options, you can use axe.configure to configure the check and modify the options as desired.
// configure has-lang check to look at the `hreflang` attribute as well
axe.configure({
checks: [
{
id: 'has-lang',
options: {
attributes: ['lang', 'xml:lang', 'hreflang']
}
}
]
});
Options
Global Options
All checks allow these global options:
| Option |
Default |
Description |
reviewOnFail |
false |
Have the check return as "Needs Review" rather than a violation |
aria-allowed-role
| Option |
Default |
Description |
allowImplicit |
true |
Allow the explicit role to match the implicit role of the element |
ignoredTags |
[] |
Do not check for allowed roles in the provided HTML elements list |
aria-prohibited-attr
| Option |
Default |
Description |
elementsAllowedAriaLabel
|
[
"audio",
"applet",
"canvas",
"dl",
"embed",
"iframe",
"input",
"label",
"meter",
"object",
"svg",
"video"
]
|
List of element names that without a role, are allowed an `aria-label` and `aria-labelledby` attribute |
aria-required-children
| Option |
Default |
Description |
reviewEmpty
|
[
'doc-bibliography',
'doc-endnotes',
'grid',
'list',
'listbox',
'table',
'tablist',
'tree',
'treegrid',
'rowgroup'
]
|
List of ARIA roles that should be flagged as "Needs Review" rather than a violation if the element has no owned children |
aria-required-parent
| Option |
Default |
Description |
ownGroupRoles
|
['listitem', 'treeitem']
|
List of ARIA roles that when used in a group can have a grand parent with the same role. E.g. list > listitem > group > listitem. |
aria-roledescription
| Option |
Default |
Description |
supportedRoles
|
[
'button',
'img',
'checkbox',
'radio',
'combobox',
'menuitemcheckbox',
'menuitemradio'
]
|
List of ARIA roles that support the aria-roledescription attribute |
color-contrast
| Option |
Default |
Description |
ignoreUnicode |
true |
Do not check the color contrast of Unicode characters |
ignoreLength |
false |
Do not check the color contrast of short text content |
boldValue |
700 |
The minimum CSS font-weight value that designates bold text |
boldTextPt |
14 |
The minimum CSS font-size pt value that designates bold text as being large |
largeTextPt |
18 |
The minimum CSS font-size pt value that designates text as being large |
shadowOutlineEmMax |
0.1 |
The maximum blur-radius value (in ems) of the CSS text-shadow property. blur-radius values greater than this value will be treated as a background color rather than an outline color. |
contrastRatio |
N/A |
Contrast ratio options |
contrastRatio.normal |
N/A |
Contrast ratio requirements for normal text (non-bold text or text smaller than largeTextPt) |
contrastRatio.normal.expected |
4.5 |
The expected contrast ratio for normal text |
contrastRatio.normal.minThreshold |
N/A |
The minimum contrast ratio the check will apply to. Contrast ratios less than this value will be ignored |
contrastRatio.normal.maxThreshold |
N/A |
The maximum contrast ratio the check will apply to. Contrast ratios greater than this value will be ignored |
contrastRatio.large |
N/A |
Contrast ratio requirements for large text (bold text or text larger than largeTextPt) |
contrastRatio.large.expected |
4.5 |
The expected contrast contrast ratio for large text |
contrastRatio.large.minThreshold |
N/A |
The minimum contrast ratio the check will apply to. Contrast ratios less than this value will be ignored |
contrastRatio.large.maxThreshold |
N/A |
The maximum contrast ratio the check will apply to. Contrast ratios greater than this value will be ignored |
page-has-heading-one
| Option |
Default |
Description |
selector
|
h1:not([role]):not([aria-level]),
h1:not([role])[aria-level=1],
h2:not([role])[aria-level=1],
h3:not([role])[aria-level=1],
h4:not([role])[aria-level=1],
h5:not([role])[aria-level=1],
h6:not([role])[aria-level=1],
[role=heading][aria-level=1]
|
Selector used to determine if a page has a level one heading |
page-has-main
| Option |
Default |
Description |
selector |
main:not([role]), [role='main'] |
Selector used to determine if a page has a main landmark |
page-no-duplicate-banner
| Option |
Default |
Description |
selector |
header:not([role]), [role=banner] |
Selector used to determine if a page has a banner landmark |
nativeScopeFilter |
article, aside, main, nav, section |
Selector used to ignore banner landmarks that have a parent that matches the selector |
page-no-duplicate-contentinfo
| Option |
Default |
Description |
selector |
footer:not([role]), [role=contentinfo] |
Selector used to determine if a page has a contentinfo landmark |
nativeScopeFilter |
article, aside, main, nav, section |
Option values used to ignore contentinfo landmarks that have a selector matching the parent element |
page-no-duplicate-main
| Option |
Default |
Description |
selector |
main:not([role]), [role='main'] |
Selector used to determine if a page has a main landmark |
duplicate-img-label
| Option |
Default |
Description |
parentSelector
|
button,
[role=button],
a[href],
p,
li,
td,
th
|
Selector used to look at an image parent that may duplicate the image label |
label-content-name-mismatch
| Option |
Default |
Description |
pixelThreshold |
0.1 |
Percent of difference in pixel data or pixel width required to determine if a font is a ligature font. Ligature fonts are ignored when comparing the label to the content |
occuranceThreshold |
3 |
Number of times the font is encountered before auto-assigning the font as a ligature or not |
has-lang
| Option |
Default |
Description |
attributes |
['lang', 'xml:lang'] |
Attributes to check for lang values |
valid-lang
| Option |
Default |
Description |
attributes |
['lang', 'xml:lang'] |
Attributes to check for valid lang values |
value |
Array of all valid langs |
List of valid lang values |
frame-tested
| Option |
Default |
Description |
isViolation |
false |
If an iframe that has not been injected with axe-core should be reported as a violation |
no-autoplay-audio
| Option |
Default |
Description |
allowedDuration |
3 |
Maximum time in seconds an audio clip may autoplay before being marked as violation |
css-orientation-lock
| Option |
Default |
Description |
degreeThreshold |
3 |
The difference of degrees from 180 and 90 that are considered locked to a specific display orientation (for example, 93° rotated is not considered locked while 94° is) |
meta-viewport-large
| Option |
Default |
Description |
scaleMinimum |
5 |
The scale-maximum CSS value of the check applies to. Values above this number will be ignored |
lowerBound |
2 |
The scale-minimum CSS value the check applies to. Values below this number will be ignored |
meta-viewport
| Option |
Default |
Description |
scaleMinimum |
2 |
The scale-maximum CSS value the check applies to. Values above this number will be ignored |
header-present
| Option |
Default |
Description |
selector
|
h1:not([role]),
h2:not([role]),
h3:not([role]),
h4:not([role]),
h5:not([role]),
h6:not([role]),
[role=heading]
|
Selector used to determine if a page has a heading |
landmark
| Option |
Default |
Description |
selector |
main, [role=main] |
Selector used to determine if a page has a landmark region |
p-as-heading
| Option |
Default |
Description |
margins
|
[
{ "weight": 150, "italic": true },
{ "weight": 150, "size": 1.15 },
{ "italic": true, "size": 1.15 },
{ "size": 1.4 }
]
|
Common CSS values used to display `p` elements as `h1-h6` elements determining if a `p` element is being improperly repurposed |
avoid-inline-spacing
| Option |
Default |
Description |
cssProperties |
['line-height', 'letter-spacing', 'word-spacing'] |
List of inline spacing CSS properties to flag |
scope-value
| Option |
Default |
Description |
values |
['row', 'col', 'rowgroup', 'colgroup'] |
List of valid scope values |
region
| Option |
Default |
Description |
regionMatcher |
dialog, [role=dialog], svg |
A matcher object or CSS selector to allow elements to be treated as regions |
