Props and methods

Props

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

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 or customize specific modules or checks.

Pass in props when you instantiate Sa11y, for example:

const sa11y = new Sa11y({
  checkRoot: "main",
  readabilityRoot: "main",
  containerIgnore: "#pagination, aside",
});

Important: The code snippets on this page display the default values for each prop. These values are automatically applied unless overridden or specified otherwise. If a snippet is intended as an example, it will be explicitly labeled as such.

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

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

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

ignoreHiddenOverflow

String. Prevent Sa11y from unhiding containers with overflow: hidden by passing specific selectors. Since 4.0.6.

ignoreHiddenOverflow: '',

Control panel

Properties that affect Sa11y's control panel.

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. Since 3.2.0.

aboutContent: '',

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

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.

colourFilterPlugin

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

colourFilterPlugin: true,

exportResultsPlugin

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

exportResultsPlugin: false,

developerChecksOnByDefault

Boolean. Set to true if you would like "Developer checks" enabled by default.

developerChecksOnByDefault: false,

checkAllHideToggles

Boolean. Set to true if you would like to visually hide the "Developer checks" toggle.

checkAllHideToggles: false,

showHinPageOutline

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

showHinPageOutline: false,

showTitleInPageOutline

Boolean. Show the page's meta title in the Page Outline. Since 3.2.2.

 showTitleInPageOutline: true,

showImageOutline

Boolean. Display the "Images" tab between the Outline and Settings tab within the control panel. Since 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. Since 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. Since 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. Since 3.2.0.

relativePathImageID: '',

Other features

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

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. Since 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. Since 3.1.2.

delayCustomCheck: 500,

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

headless

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

headless: false,

selectorPath

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

selectorPath: false,

shadowComponents

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

shadowComponents: '',

autoDetectShadowComponents

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

autoDetectShadowComponents: false,

customChecks

Please refer to custom checks for guidance. Since 3.0.0.

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,

Annotations

Props related to annotations.

dismissAnnotations

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

dismissAnnotations: true,

dismissAll

Boolean. Set to false to turn off "Dismiss all" functionality for all tooltips. Note, only some checks have a "Dismiss all" button by default. Since 4.0.0.

dismissAll: true,

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,

insertAnnotationBefore

String. Using unique selectors, change the location of where annotations are inserted around the issue's element. This is particularly useful for containers where annotations are inaccessible due to issues like z-index values or other layout constraints. For example, you can use this prop to ensure any annotations gets added outside of the element's parent container, like a closed accordion component.

insertAnnotationBefore: '',

Customize checks

As of 4.0, any check can be individually turned off or customized upon instantiation. To customize or turn off a check, find the desired key within the language file or default options. You can easily change a:

• Tooltip’s message.
• Classification as a warning or error.
• Classification as a “Developer check”.
• Give “Dismiss all” ability to a check.

Here's an example:

const sa11y = new Sa11y({
  checkRoot: "main",
  checks: {

    // Turn off the "Missing Heading 1" check.
    HEADING_MISSING_ONE: false,

    // Change "Empty table heading" error to a warning,
    // overwrite tooltip content, and
    // allow editors to "Dismiss all"
    TABLES_EMPTY_HEADING: {
      content: 'Please avoid empty table headers within tables!',
      type: 'warning',
      dismissAll: true,
    }

    // Adjust max character count of "Alt is too long" check.
    LINK_IMAGE_LONG_ALT: {
      maxLength: 100,
    },
    IMAGE_ALT_TOO_LONG: {
      maxLength: 100,
    },
  }
});

The props below are shared between different checks and are not nested under the "checks" object.

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. Since 3.2.0.

susAltStopWords: '',

linkStopWords

String. Overwrite the WARNING_ALT_STOPWORDS array (e.g. click here) in the language files. Since 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. Since 3.2.0.

extraPlaceholderStopWords: '',

imageWithinLightbox

String. Use this prop to customize how images within links are processed. This is ideal for scenarios like lightboxes or image galleries, where images are wrapped in anchor tags solely for magnifying purposes. In such cases, the tooltip will provide more appropriate guidance, as these images are not typical functional links pointing to specific URLs. To configure, pass a unique selector specific to the anchor wrapped around the lightbox image. For example, pass .lightbox for <a href="#" class="lightbox"><img src="car.png" alt/></a>. Since 4.0.7.

imageWithinLightbox: '',

contrastPlugin

Boolean. Set to false to turn off all contrast checking.

contrastPlugin: true,

formLabelsPlugin

Boolean. Set to false to turn off all input/form labels checks.

formLabelsPlugin: 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: "";

Deprecated props

The following props are deprecated, but their functionality can still be achieved using the new props structure for checks.

linksAdvancedPlugin: true,

nonConsecutiveHeadingIsError: true,

flagLongHeadings: true,

missingH1: true,

altTextMaxCharLength: 250,

headingMaxCharLength: 170,

URLTextMaxCharLength: 40,

URLAsLinkTextWarning: true,

badLinksQA: true,

strongItalicsQA: true,

pdfQA: true,

documentQA: true,

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

blockquotesQA: true,

tablesQA: true,

allCapsQA: true,

fakeHeadingsQA: true,

fakeListQA: true,

duplicateIdQA: true,

underlinedTextQA: true,

pageTitleQA: true,

subscriptQA: true,

tablesQAmissingTH: true,

tablesQAsemanticHeadings: true,

tablesQAemptyTH: true,

tablesQAemptyTHisError: true,

embeddedContentAll: true,

embeddedContentAudio: true,

embeddedContentVideo: true,

embeddedContentDataViz: true,

embeddedContentTitles: true,

embeddedContentGeneral: true,

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

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

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.