Skip to content

Latest commit

 

History

History
601 lines (513 loc) · 27.3 KB

check-options.md

File metadata and controls

601 lines (513 loc) · 27.3 KB

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

aria-allowed-attr

Previously supported properties validTreeRowAttrs is no longer available. invalidTableRowAttrs from aria-conditional-attr instead.

aria-conditional-attr

Option Default Description
invalidTableRowAttrs 
[
  'aria-posinset',
  'aria-setsize',
  'aria-expanded',
  'aria-level',
]
 List of ARIA attributes that are not allowed on role=row when a descendant of a table or a grid

autocomplete-valid

Option Default Description
stateTerms 
[
  'none',
  'false',
  'true',
  'disabled',
  'enabled',
  'undefined',
  'null',
]
 List of allowed autocomplete state terms other than "on" and "off."
ignoredValues 
[
  'text',
  'pronouns',
  'gender',
  'message',
  'content'
]
 List of autocomplete values that are technically invalid but will be ignored as they may not necessarily cause accessibility problems

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
ignorePseudo false Do not mark pseudo elements as Needs Review
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.
textStrokeEmMin 0.03 The minimum EM width of -webkit-text-stroke before axe uses the text stroke color over the actual text color.
pseudoSizeThreshold 0.25 Minimum area of the pseudo element, relative to the text element, below which it will be ignored for colot contrast.
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
occurrenceThreshold 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

meta-refresh

Option Default Description
minDelay 0 Passes if the redirect is equal or less than this. Can be set to false to disable
maxDelay 7200 Passes if the redirect is greater than this. Can be set to false to disable

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
passLength 
"passLength": 1
 Relative length, if the the candidate heading is X times or greater the length of the candidate paragraph, it will pass.
faiLength 
"failLength": 0.5
 Relative length, if the the candidate heading is X times or less the length of the candidate paragraph, it can fail.

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

target-offset

Option Default Description
minOffset 24 Minimum space required from the farthest edge of the target, to the closest edge of the neighboring target

target-size

Option Default Description
minSize 24 Minimum width and height a component should have, that is not obscured by some other interactive element

region

Option Default Description
regionMatcher 
dialog, [role=dialog], svg
 A matcher object or CSS selector to allow elements to be treated as regions

inline-style-property-evaluate

This evaluate method is used in the following checks. Default vary between checks

  • important-letter-spacing
  • important-word-spacing
  • important-line-height
Option Description
cssProperty Which property to check the value of, for example letter-spacing or font-size
absoluteValues Whether or not to calculate value in pixels (true) or in em (false)
noImportant While false, the check returns true except if !important is used
multiLineOnly If true,
minValue Returns false when the value is less than minValue
maxValue Returns false when the value is more than maxValue
normalValue The value to use when normal is set, defaults to 0

If minValue and maxValue are both undefined, the check returns false if the property is used with !important. If done along with noImportant: true, the check returns false if the property is set at all in the style attribute.

invalid-children

This evaluation method is used in the list and definition-list rule to determine whether its child nodes are allowed.

Option Description
validNodeNames Nodes without role allowed as children
validRoles Roles allowed on child elements
divGroups Whether the child nodes can be grouped in a div without any role (false by default)

link-in-text-block

This evaluation method is used in the link-in-text-block rule and tests that either the foreground color or the background color has sufficient contrast between the link text and the surrounding text.

Option Default Description
requiredContrastRatio 3 Minimum contrast needed to pass the check between text or background colors
allowSameColor true Whether links with colors identical to its surroundings should pass