Accessibility preset rule configs for axe
import axe from 'axe-core';
import { recommended } from '@sa11y/preset-rules';
const a11yResults = await axe.run(recommended);
console.log(a11yResults);@sa11y/preset-rules provides three pre-configured rulesets curated from axe: Base, Recommended and Full.
- Below is the full set of rules from axe rule descriptions and their current mapping to the Base and Recommended rulesets in @sa11y/preset-rules.
- Full ruleset consists of all rules that are enabled by default in axe.
| Rule ID | Description | Impact | Issue Type | In Base Ruleset | In Recommended Ruleset | Notes |
|---|---|---|---|---|---|---|
| area-alt | Ensures <area> elements of image maps have alternate text | Critical | failure | ✔️ | ✔️ | |
| aria-allowed-attr | Ensures ARIA attributes are allowed for an element's role | Critical | failure | ✔️ | ✔️ | |
| aria-hidden-body | Ensures aria-hidden='true' is not present on the document body. | Critical | failure | ✔️ | ✔️ | |
| aria-hidden-focus | Ensures aria-hidden elements do not contain focusable elements | Serious | failure, needs review | ✔️ | ✔️ | |
| aria-input-field-name | Ensures every ARIA input field has an accessible name | Moderate, Serious | failure, needs review | ✔️ | ✔️ | |
| aria-required-attr | Ensures elements with ARIA roles have all required ARIA attributes | Critical | failure | ✔️ | ✔️ | |
| aria-required-children | Ensures elements with an ARIA role that require child roles contain them | Critical | failure, needs review | ✔️ | ✔️ | |
| aria-required-parent | Ensures elements with an ARIA role that require parent roles are contained by them | Critical | failure | ✔️ | ✔️ | |
| aria-roledescription | Ensure aria-roledescription is only used on elements with an implicit or explicit role | Serious | failure, needs review | ✔️ | ✔️ | |
| aria-roles | Ensures all elements with a role attribute use a valid value | Serious, Critical | failure | ✔️ | ✔️ | |
| aria-toggle-field-name | Ensures every ARIA toggle field has an accessible name | Moderate, Serious | failure, needs review | ✔️ | ✔️ | |
| aria-valid-attr-value | Ensures all ARIA attributes have valid values | Critical | failure, needs review | ✔️ | ✔️ | |
| aria-valid-attr | Ensures attributes that begin with aria- are valid ARIA attributes | Critical | failure | ✔️ | ✔️ | |
| audio-caption | Ensures <audio> elements have captions | Critical | needs review | ✔️ | ✔️ | |
| blink | Ensures <blink> elements are not used | Serious | failure | ✔️ | ✔️ | |
| button-name | Ensures buttons have discernible text | Critical | failure | ✔️ | ✔️ | |
| bypass | Ensures each page has at least one mechanism for a user to bypass navigation and jump straight to the content | Serious | failure | ✔️ | ✔️ | |
| color-contrast | Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds | Serious | failure, needs review | ✔️ | ✔️ | |
| dlitem | Ensures <dt> and <dd> elements are contained by a <dl> | Serious | failure | ✔️ | ✔️ | |
| document-title | Ensures each HTML document contains a non-empty <title> element | Serious | failure | ✔️ | ✔️ | |
| duplicate-id-active | Ensures every id attribute value of active elements is unique | Serious | failure | ✔️ | ✔️ | |
| duplicate-id-aria | Ensures every id attribute value used in ARIA and in labels is unique | Critical | failure | ✔️ | ✔️ | |
| duplicate-id | Ensures every id attribute value is unique | Minor | failure | ✔️ | ✔️ | |
| form-field-multiple-labels | Ensures form field does not have multiple label elements | Moderate | needs review | ✔️ | ✔️ | |
| frame-title | Ensures <iframe> and <frame> elements contain a non-empty title attribute | Serious | failure | ✔️ | ✔️ | |
| html-has-lang | Ensures every HTML document has a lang attribute | Serious | failure | ✔️ | ✔️ | |
| html-lang-valid | Ensures the lang attribute of the <html> element has a valid value | Serious | failure | ✔️ | ✔️ | |
| html-xml-lang-mismatch | Ensure that HTML elements with both valid lang and xml:lang attributes agree on the base language of the page | Moderate | failure | ✔️ | ✔️ | |
| image-alt | Ensures <img> elements have alternate text or a role of none or presentation | Critical | failure | ✔️ | ✔️ | |
| input-button-name | Ensures input buttons have discernible text | Critical | failure | ✔️ | ✔️ | |
| input-image-alt | Ensures <input type="image"> elements have alternate text | Critical | failure | ✔️ | ✔️ | |
| label | Ensures every form element has a label | Minor, Critical | failure | ✔️ | ✔️ | |
| link-name | Ensures links have discernible text | Serious | failure | ✔️ | ✔️ | |
| list | Ensures that lists are structured correctly | Serious | failure | ✔️ | ✔️ | |
| listitem | Ensures <li> elements are used semantically | Serious | failure | ✔️ | ✔️ | |
| marquee | Ensures <marquee> elements are not used | Serious | failure | ✔️ | ✔️ | |
| meta-refresh | Ensures <meta http-equiv="refresh"> is not used | Critical | failure | ✔️ | ✔️ | |
| object-alt | Ensures <object> elements have alternate text | Serious | failure | ❌ | ✔️ | <obj> rarely used |
| role-img-alt | Ensures [role='img'] elements have alternate text | Serious | failure | ✔️ | ✔️ | |
| scrollable-region-focusable | Elements that have scrollable content should be accessible by keyboard | Moderate | failure | ✔️ | ✔️ | |
| server-side-image-map | Ensures that server-side image maps are not used | Minor | needs review | ✔️ | ✔️ | |
| svg-img-alt | Ensures svg elements with an img, graphics-document or graphics-symbol role have an accessible text | Serious | failure | ✔️ | ✔️ | |
| td-headers-attr | Ensure that each cell in a table using the headers refers to another cell in that table | Serious | failure, needs review | ✔️ | ✔️ | |
| th-has-data-cells | Ensure that each table header in a data table refers to data cells | Serious | failure, needs review | ✔️ | ✔️ | |
| valid-lang | Ensures lang attributes have valid values | Serious | failure | ✔️ | ✔️ | |
| video-caption | Ensures <video> elements have captions | Critical | needs review | ✔️ | ✔️ |
| Rule ID | Description | Impact | Issue Type | In Base Ruleset | In Recommended Ruleset | Notes |
|---|---|---|---|---|---|---|
| autocomplete-valid | Ensure the autocomplete attribute is correct and suitable for the form field | Serious | failure | ✔️ | ✔️ | |
| avoid-inline-spacing | Ensure that text spacing set through style attributes can be adjusted with custom stylesheets | Serious | failure | ❌ | ✔️ | TBD on how widespread this issue is |
Rules that do not necessarily conform to WCAG success criterion but are industry accepted practices that improve the user experience.
| Rule ID | Description | Impact | Issue Type | In Base Ruleset | In Recommended Ruleset | Notes |
|---|---|---|---|---|---|---|
| accesskeys | Ensures every accesskey attribute value is unique | Serious | failure | ❌ | ✔️ | Rarely applicable |
| aria-allowed-role | Ensures role attribute has an appropriate value for the element | Minor | failure, needs review | ❌ | ✔️ | |
| empty-heading | Ensures headings have discernible text | Minor | failure | ✔️ | ✔️ | |
| frame-tested | Ensures <iframe> and <frame> elements contain the axe-core script | Critical | failure, needs review | ❌ | ✔️ | |
| frame-title-unique | Ensures <iframe> and <frame> elements contain a unique title attribute | Serious | failure | ❌ | ❌ | May not be able to control for this on highly customizable pages with many embedded components |
| heading-order | Ensures the order of headings is semantically correct | Moderate | failure | ✔️ | ✔️ | |
| identical-links-same-purpose | Ensure that links with the same accessible name serve a similar purpose | Minor | needs review | ❌ | ✔️ | May not be able to control for this on highly customizable pages with many embedded components |
| image-redundant-alt | Ensure image alternative is not repeated as text | Minor | failure | ✔️ | ✔️ | Common bug worth catching! |
| label-title-only | Ensures that every form element is not solely labeled using the title or aria-describedby attributes | Serious | failure | ✔️ | ✔️ | |
| landmark-banner-is-top-level | Ensures the banner landmark is at top level | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| landmark-complementary-is-top-level | Ensures the complementary landmark or aside is at top level | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| landmark-contentinfo-is-top-level | Ensures the contentinfo landmark is at top level | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| landmark-main-is-top-level | Ensures the main landmark is at top level | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| landmark-no-duplicate-banner | Ensures the document has at most one banner landmark | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| landmark-no-duplicate-contentinfo | Ensures the document has at most one contentinfo landmark | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| landmark-no-duplicate-main | Ensures the document has at most one main landmark | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| landmark-one-main | Ensures the document has a main landmark | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| landmark-unique | Landmarks must have a unique role or role/label/title (i.e. accessible name) combination | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| meta-viewport-large | Ensures <meta name="viewport"> can scale a significant amount | Minor | failure | ❌ | ✔️ | |
| meta-viewport | Ensures <meta name="viewport"> does not disable text scaling and zooming | Critical | failure | ❌ | ✔️ | |
| page-has-heading-one | Ensure that the page, or at least one of its frames contains a level-one heading | Moderate | failure | ✔️ | ✔️ | This should always be true |
| region | Ensures all page content is contained by landmarks | Moderate | failure | ❌ | ✔️ | Still have landmark work to do before enabling in "Base" set |
| scope-attr-valid | Ensures the scope attribute is used correctly on tables | Moderate, Critical | failure | ✔️ | ✔️ | This should always be true |
| skip-link | Ensure all skip links have a focusable target | Moderate | failure, needs review | ❌ | ❌ | Strict test for in-page links, doesn't pass for JS skip links |
| tabindex | Ensures tabindex attribute values are not greater than 0 | Serious | failure | ✔️ | ✔️ | This should always be true |
| table-duplicate-name | Ensure that tables do not have the same summary and caption | Minor | failure | ❌ | ❌ | Table captions rarely used in our apps |
Rules we are still testing and developing. They are not enabled by default in axe-core, but are enabled for the axe browser extensions.
| Rule ID | Description | Impact | Issue Type | In Base Ruleset | In Recommended Ruleset | Notes |
|---|---|---|---|---|---|---|
| css-orientation-lock | Ensures content is not locked to any specific display orientation, and the content is operable in all display orientations | Serious | failure, needs review | ❌ | ✔️ | |
| focus-order-semantics | Ensures elements in the focus order have an appropriate role | Minor | failure | ✔️ | ✔️ | |
| hidden-content | Informs users about hidden content. | Minor | failure, needs review | ❌ | ❌ | Can have false positives |
| label-content-name-mismatch | Ensures that elements labelled through their content must have their visible text as part of their accessible name | Serious | failure | ❌ | ✔️ | |
| link-in-text-block | Links can be distinguished without relying on color | Serious | failure, needs review | ❌ | ✔️ | |
| no-autoplay-audio | Ensures <video> or <audio> elements do not autoplay audio for more than 3 seconds without a control mechanism to stop or mute the audio | Moderate | failure, needs review | ❌ | ✔️ | |
| p-as-heading | Ensure p elements are not used to style headings | Serious | failure | ❌ | ✔️ | |
| table-fake-caption | Ensure that tables with a caption use the <caption> element. | Serious | failure | ❌ | ❌ | Table captions rarely used in our apps |
| td-has-header | Ensure that each non-empty data cell in a large table has one or more table headers | Critical | failure | ✔️ | ✔️ |