Props & methods


Props allow you to easily customize the experience for content authors. For example:

  1. Set the target area to check. If your content authors can't edit it, don't flag it!
  2. Ignore entire sections of a page.
  3. Add exclusions to ignore false positives.
  4. Turn off specific modules or checks.

Pass in props when you instantiate Sa11y, for example:

const sa11y = new Sa11y({
  checkRoot: "main",
  readabilityRoot: "main",
  formLabelsPlugin: false,
  containerIgnore: "#pagination, aside",

Target area and exclusions

Identify elements by CSS selectors or HTML sectioning elements. Use a comma to pass multiple selector unless otherwise indicated.


String. Input a single selector to scan a specific region of the page. This selector should exist on every page of your website. For example, pass main for the main content area.

checkRoot: 'body',


String. Ignore specific regions of the page.

containerIgnore: '.sa11y-ignore',


String. Ignore specific elements from the contrast check.

contrastIgnore: '.sr-only, [role="menu"] *',


String. Exclude specific headings from appearing in the Page Outline panel. For example, visually hidden headings that may not make sense to sighted content editors.

outlineIgnore: '',


String. Ignore specific headings on the page. These headings will not be annotated or labeled, nor will they appear in the Page Outline.

headerIgnore: '',


String. Ignore specific images on the page.

imageIgnore: '',


String. Ignore specific links on the page.

linkIgnore: 'nav, [role="navigation"]',


String. Ignore elements within a link or image link to improve accuracy of link checks.

linkIgnoreSpan: '',

The contents of <span class="sr-only"> will be ignored, and the non-descript link will display the appropriate error annotation.

<a href="">learn more <span class="sr-only">external link</span></a>

  const sa11y = new Sa11y({
    linkIgnoreSpan: '.sr-only',

Try: Press alt A to enable Sa11y.

learn more external link


String. An alternative prop to linkIgnoreSpan. Pass a string of regex that matches specific words or phrases. For example, "\(External\)|\(Opens new tab\)".

linkIgnoreStrings: '',


String. Check for unwanted URLs, such as those pointing to development environments. For example, a[href*="dev."]

linksToFlag: '',

Other features

Features that may help with integrations into various content management systems or frameworks.


Integer. Defer the initial page check by a customizable delay of x milliseconds. Useful for accommodating slower-loading JavaScript elements. For example, pass 500 to delay the initial check by 500 milliseconds. Available as of 3.0.9.

delayCheck: 0,


Integer. Extend or decrease the amount of time that Sa11y will wait for any custom checks provided via dispatched events. Refer to Custom Checks for guidance. Available as of 3.1.2.

delayCheck: 500,


Boolean. Show "Good" annotations on links with an accessible name that was defined with an aria-label or aria-labelledby attribute. Sometimes content authors may wonder why some "learn more" links are not flagged as an error.

showGoodLinkButton: true,


Boolean. Detects URL changes and re-checks the page. This prop is designed to improve usability when testing JavaScript rendered content or single page applications (SPA).

detectSPArouting: false,


String. Using a comma seperated list, provide selectors to unique pages where you do not want Sa11y to appear or check.

doNotRun: '',


Boolean. Give content editors the ability to dismiss any warnings.

dismissAnnotations: true,


Boolean. Run checks without the GUI (graphical user interface).

headless: false,


Boolean. Generates a simple CSS selector path of the element within the results array.

selectorPath: false,


String. Provide a list of all known web components to check.

shadowComponents: '',


Boolean. Automatically check every element on the page for an open shadow DOM, and check for issues within them.

autoDetectShadowComponents: false,


String. Move position of panel in any four corners. Choose from top-left, top-right, left, and right.

panelPosition: 'right',

Accessibility note: When the panel is positioned to the left side, the CSS property flex-direction: row-reverse is used to reverse the items within the main panel status which contains the issue count, Skip-to-issue button and Dismiss button. This causes a disconnect between the visual order and DOM order.


Boolean. Prefix each item within the Page Outline with an H.

showHinPageOutline: false,


Please refer to custom checks for guidance.

  1. Pass listen if you would like Sa11y to "listen" for custom checks.
  2. Pass an object if you would like to add custom checks before instantiating Sa11y.
  3. Set to true if Sa11y is installed locally on your system and add custom checks to sa11y-custom-checks.js file.
customChecks: false,

Customizing rulesets

Use these props to customize specific rulesets.


Boolean. Set to false if you would like skipped headings to be flagged as a warning instead. By default Sa11y flags skipped headings as an error, however, this is not a WCAG failure.

nonConsecutiveHeadingIsError: true,


Boolean. Flag headings longer than 170 characters. This is not a WCAG criterion.

flagLongHeadings: true,


Boolean. Set to false if you would like to turn off this ruleset.

missingH1: true,


Integer. Modify the alt text character count for warning message about excessively long alt.

altTextMaxCharLength: 250,


Integer. Modify the heading text character count for warning message about excessively long headings.

headingMaxCharLength: 170,


Integer. Modify the URL text character count for warning message about URLs used as link text.

URLTextMaxCharLength: 40,


Boolean. Set to false to turn off warning message about URLs used as link text.

URLAsLinkTextWarning: true,

Readability module

The readability module is based on Flesch reading ease.


Boolean. Set to false to turn off and hide Readability check from the Settings panel.

readabilityPlugin: true,


String. Target area for readability check. For example, pass main for main content area. Accepts a single selector only.

readabilityRoot: 'body'


String. Ignore specific content from readability check. <li> tags within navigation landmarks are excluded by default.

readabilityIgnore: ''

Toggleable rulesets in Settings panel

Turn off specific checks within the Settings panel.


Boolean. Set to false to turn off and hide contrast check from Settings panel.

contrastPlugin: true,


Boolean. Set to false to turn off and hide Form labels check from Settings panel.

formLabelsPlugin: true,


Boolean. Set to false to turn off and hide Links (Advanced) check from Settings panel.

linksAdvancedPlugin: true,


Boolean. Set to false to turn off and hide Colour filters from Settings panel.

colourFilterPlugin: true,


Boolean. Set to true if you would like to visually hide all toggle switches in the Settings panel. This will not hide the Dark Mode or Colour Filter toggles.

checkAllHideToggles: false,


Boolean. Set to true if you would like to add buttons that allow users to export issues as CSV or HTML.

exportResultsPlugin: false,

Quality assurance module

Turn off or modify specific quality assurance checks.


Boolean. Related to linksToFlag prop.

badLinksQA: true,


Boolean. Flags entire paragraphs that are bold or italicized.

strongItalicsQA: true,


Boolean. Warning about PDF content.

pdfQA: true,


Boolean. Warning for Office and Google Workspace documents.

documentQA: true,


String. Default values for documentQA prop.

documentLinks: '.ppt, .doc, .xls, .csv,,',


Boolean. Error if page language is not set.

langQA: true,


Boolean. Warning if blockquote suspiciously resembles a heading.

blockquotesQA: true,


Boolean. Various errors about inaccessible HTML tables.

tablesQA: true,


Boolean. Warning about use of ALL CAPS. Note: Sometimes this check can be problematic because of regex usage. Set to false if you experience any issues.

allCapsQA: true,


Boolean. Warning about bolded text that suspiciously resembles a heading. Uses regex.

fakeHeadingsQA: true,


Boolean. Warning about suspiciously formatted content that should be a semantic list.

fakeListQA: true,


Boolean. Error if duplicate id exists on the page.

duplicateIdQA: true,


Boolean. Warning for underlined text.

underlinedTextQA: true,


Boolean. Error if meta page <title> is missing or empty.

pageTitleQA: true,


Boolean. Warning if <sup> and <sub> tags are used to format entire sentences.

subscriptQA: true,


Set to false to turn off check that flags missing table headers as an error.

tablesQAmissingTH: true,


Set to false to turn off check that flags semantic headings within a table as an error.

tablesQAsemanticHeadings: true,


Set to false to turn off check that flags empty table headers within a table as an error.

tablesQAemptyTH: true,


Set to false to change check that flags empty table headers from an error to a warning.

tablesQAemptyTHisError: true,

Embedded content (iFrames) module

All properties related to embedded content checks.


Boolean. Set to false to ignore all iFrames.

embeddedContentAll: true,


Boolean. Warning about audio content and transcripts.

embeddedContentAudio: true,


Boolean. Warning about video content and captions.

embeddedContentVideo: true,


Boolean. Warning about data visualizations.

embeddedContentDataViz: true,


Boolean. Warning about iFrame missing a descriptive title or accessible name.

embeddedContentTitles: true,


Boolean. General warning about unknown iFrame content.

embeddedContentGeneral: true,


String. Common video players.

videoContent: 'video,,,,',


String. Common podcast widgets or audio players.

audioContent: 'audio,,,,,,,,',


String. Common data visualization widgets.

dataVizContent: ', tableau',


These helper methods streamline integration into content management systems.


Use this function to reset Sa11y's interface and remove all annotations from the page. Pass false as a parameter to reset the page while keeping Sa11y's panel open.


Utilize this function to initiate another scan of the page. You can optionally pass different selectors for checkRoot and readabilityRoot than those initially specified upon instantiation, like so: sa11y.checkAll(checkRoot, readabilityRoot);.


View a live demo of "travelling" roots.

// Initial instantiation.
const sa11y = new Sa11y.Sa11y({
  checkRoot: "main",
  readabilityRoot: "main",

// Re-checks the page after 2 seconds.
setTimeout(() => {
}, 2000);

// Re-checks the page after 4 seconds, but with different target roots.
setTimeout(() => {
  sa11y.checkAll("body", "body");
}, 4000);


Employ this function to temporarily deactivate the accessibility checker. It closes the panel (if open) and applies the disabled attribute, graying out the toggle and blocking user interaction.


Utilize this function to restore functionality to the accessibility checker. It removes the disabled attribute from the primary toggle, enabling users to interact with it again.

sa11y.find(selector, desiredRoot, exclude)

This is a powerful utility to find elements in the DOM that match the given selector. It will also find elements with any specified shadow DOMs. It can accept up to 3 parameters and returns an array of elements.

  • selector (string) - The CSS selector to match elements against, e.g. a[href]
  • desiredRoot (string) - The root element to start the search from. Can be one of 'document', 'readability', 'root', or a custom selector for the desired root element. In most cases, you should pass root which is the root area that Sa11y was specified to check.
  • Optional exclude (string) - Elements to exclude from the search, specified as a CSS selector.


const links = sa11y.find('a[href]', 'root', '.ignore');

This will return an array of links (with an href attribute) within the area that Sa11y was specified to target via the checkRoot prop. It excludes any links that have the class .ignore.


Create a dismissal key to facilitate the dismissal of items. This feature is essential if you want to enable custom warning dismissibility.


This function takes a string containing HTML as input and returns a sanitized version where special characters are replaced with their respective HTML entities. It's particularly useful when returning text within a tooltip, ensuring that any potentially harmful content is properly escaped to prevent security vulnerabilities.


Provide feedback on props via GitHub or Report a bug.