Props & methods

Props

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.

checkRoot

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',

containerIgnore

String. Ignore specific regions of the page.

containerIgnore: '.sa11y-ignore',

contrastIgnore

String. Ignore specific elements from the contrast check.

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

outlineIgnore

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: '',

headerIgnore

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

headerIgnore: '',

imageIgnore

String. Ignore specific images on the page.

imageIgnore: '',

linkIgnore

String. Ignore specific links on the page.

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

linkIgnoreSpan

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

linkIgnoreSpan: '',

<a href="https://www.example.com">learn more <span class="sr-only">external link</span></a>

<script>
  const sa11y = new Sa11y({
    linkIgnoreSpan: '.sr-only',
  });
</script>

linkIgnoreStrings

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

linkIgnoreStrings: '',

linksToFlag

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

linksToFlag: '',

headerIgnoreSpan

String. Ignore elements within headings to enhance the accuracy of checks and ensure that text isn't displayed within the Page Outline. For example, this prop is used on this very website to exclude the text "Anchor" from the Page Outline.

headerIgnoreSpan: '',

headerIgnoreStrings

String. An alternative prop to headerIgnoreSpan. Pass a string of regex that matches specific words or phrases to be excluded from Page Outline or heading checks. For example, "\(Anchor\)".

headerIgnoreStrings: '',

Other features

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

aboutContent

String. Add a custom "About" or "Help" section within the Settings panel. This prop should only ever be populated with static content by developers to mitigate XSS attacks. Available as of 3.2.0.

aboutContent: '<h2>Help</h2><p>Questions? Contact the IT Help Desk for support.</p>',

delayCheck

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,

delayCustomCheck

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,

showGoodLinkButton

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,

showGoodImageButton

Boolean. Show "Good" annotations on images that have alt text.

showGoodImageButton: true,

detectSPArouting

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,

doNotRun

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

doNotRun: '',

dismissAnnotations

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

dismissAnnotations: true,

headless

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

headless: false,

selectorPath

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

selectorPath: false,

shadowComponents

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

shadowComponents: '',

autoDetectShadowComponents

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

autoDetectShadowComponents: false,

panelPosition

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.

showHinPageOutline

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

showHinPageOutline: false,

customChecks

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,

showImageOutline

Boolean. Display the "Images" tab between the Outline and Settings tab within the control panel. Available as of 3.2.0.

showImageOutline: true,

editImageURLofCMS

String. Required prop to help configure "Edit" buttons for Image outline. The content management system's edit URL or path for an image. For example, /wp-admin/upload.php?item= or https://example.com/assets.html/content/dam. Available as of 3.2.0.

editImageURLofCMS: '',

relativePathImageSRC

String. Optional prop to help configure "Edit" buttons for Image outline. This prop is only necessary if images are uploaded to another domain, otherwise it uses the website's host name to check if the image has a relative path. Available as of 3.2.0.

relativePathImageSRC: '',

relativePathImageID

String. Optional prop to help configure "Edit" buttons for Image outline. Some content management system's output a unique class name which includes the image's unique ID, for example wp-image- for WordPress. If no string is provided, it will fallback to the image's file extension. Available as of 3.2.0.

relativePathImageID: '',

Customizing rulesets

Use these props to customize specific rulesets.

nonConsecutiveHeadingIsError

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,

flagLongHeadings

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

flagLongHeadings: true,

missingH1

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

missingH1: true,

altTextMaxCharLength

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

altTextMaxCharLength: 250,

susAltStopWords

String. Overwrite the SUSPICIOUS_ALT_STOPWORDS array (e.g. image of, graphic of) within the language files. For instance, by passing 'image', only alt text containing the word 'image' at the beginning will be flagged. Available as of 3.2.0.

susAltStopWords: '',

linkStopWords

String. Overwrite the WARNING_ALT_STOPWORDS array (e.g. click here) in the language files. Available as of 3.2.0.

linkStopWords: '',

extraPlaceholderStopWords

String. Add additional stop words to flag at the beginning of an alt text string as a placeholder error. For example, if you pass the word "untitled", any image whose alt text starts with "untitled" will be flagged. Available as of 3.2.0.

extraPlaceholderStopWordss: '',

headingMaxCharLength

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

headingMaxCharLength: 170,

URLTextMaxCharLength

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

URLTextMaxCharLength: 40,

URLAsLinkTextWarning

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.

readabilityPlugin

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

readabilityPlugin: true,

readabilityRoot

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

readabilityRoot: 'body'

readabilityIgnore

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.

contrastPlugin

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

contrastPlugin: true,

formLabelsPlugin

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

formLabelsPlugin: true,

linksAdvancedPlugin

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

linksAdvancedPlugin: true,

colourFilterPlugin

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

colourFilterPlugin: true,

checkAllHideToggles

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,

exportResultsPlugin

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.

badLinksQA

Boolean. Related to linksToFlag prop.

badLinksQA: true,

strongItalicsQA

Boolean. Flags entire paragraphs that are bold or italicized.

strongItalicsQA: true,

pdfQA

Boolean. Warning about PDF content.

pdfQA: true,

documentQA

Boolean. Warning for Office and Google Workspace documents.

documentQA: true,

documentLinks

String. Default values for documentQA prop.

documentLinks: 'a[href$=".doc"], a[href$=".docx"], a[href*=".doc?"], a[href*=".docx?"], a[href$=".ppt"], a[href$=".pptx"], a[href*=".ppt?"], a[href*=".pptx?"], a[href^="https://docs.google"], a[href^="https://sway."]',

langQA

Boolean. Error if page language is not set.

langQA: true,

blockquotesQA

Boolean. Warning if blockquote suspiciously resembles a heading.

blockquotesQA: true,

tablesQA

Boolean. Various errors about inaccessible HTML tables.

tablesQA: true,

allCapsQA

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,

fakeHeadingsQA

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

fakeHeadingsQA: true,

fakeListQA

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

fakeListQA: true,

duplicateIdQA

Boolean. Error if duplicate id exists on the page.

duplicateIdQA: true,

underlinedTextQA

Boolean. Warning for underlined text.

underlinedTextQA: true,

pageTitleQA

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

pageTitleQA: true,

subscriptQA

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

subscriptQA: true,

tablesQAmissingTH

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

tablesQAmissingTH: true,

tablesQAsemanticHeadings

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

tablesQAsemanticHeadings: true,

tablesQAemptyTH

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

tablesQAemptyTH: true,

tablesQAemptyTHisError

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.

embeddedContentAll

Boolean. Set to false to ignore all iFrames.

embeddedContentAll: true,

embeddedContentAudio

Boolean. Warning about audio content and transcripts.

embeddedContentAudio: true,

embeddedContentVideo

Boolean. Warning about video content and captions.

embeddedContentVideo: true,

embeddedContentDataViz

Boolean. Warning about data visualizations.

embeddedContentDataViz: true,

embeddedContentTitles

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

embeddedContentTitles: true,

embeddedContentGeneral

Boolean. General warning about unknown iFrame content.

embeddedContentGeneral: true,

videoContent

String. Common video players.

videoContent: 'video, youtube.com, vimeo.com, yuja.com, panopto.com',

audioContent

String. Common podcast widgets or audio players.

audioContent: 'audio, soundcloud.com, simplecast.com, podbean.com, buzzsprout.com, blubrry.com, transistor.fm, fusebox.fm, libsyn.com',

dataVizContent

String. Common data visualization widgets.

dataVizContent: 'datastudio.google.com, tableau',

Methods

These helper methods streamline integration into content management systems.

sa11y.resetAll();

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.

sa11y.checkAll();

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);.

// Initial instantiation.
Sa11y.Lang.addI18n(Sa11yLangEn.strings);
const sa11y = new Sa11y.Sa11y({
  checkRoot: "main",
  readabilityRoot: "main",
});

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

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

sa11y.disabled();

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.

sa11y.enable();

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.

sa11y.prepareDismissal(string)

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

sa11y.sanitizeHTML(string)

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.

Feedback

Provide feedback on props via GitHub or Report a bug.