Props

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

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

Example

<script>
    const sa11y = new Sa11y({
        checkRoot: 'main',
        readabilityRoot: 'main',
        formLabelsPlugin: false,
        containerIgnore: '#pagination, aside'
    });
</script>

Target area and exclusions

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

PropDefaultDescription
checkRoot'body'The main target area you would like Sa11y to check. For example, pass main for main content area. Accepts a single selector only.
containerIgnore'.sa11y-ignore'Ignore specific regions of the page.
contrastIgnore'.sr-only'Ignore specific elements from contrast check.
outlineIgnore''Exclude specific headings from appearing in the Show Outline panel. For example, visually hidden headings that may not make sense to sighted people.
headerIgnore''Ignore specific headings on the page (will not recieve annotations, appear in the Show Outline panel or recieve a heading label).
imageIgnore''Ignore specific images on the page.
linkIgnore'nav, [role="navigation"]'Ignore specific links on the page.
linkIgnoreSpan''Ignore elements within a link to improve accuracy of link checks. For example, pass .sr-only to ignore the text "external link": <a href="#">learn more <span class="sr-only">external link</span></a>
linksToFlag''Check for URLs that you do not want your content authors linking to. For example, absolute URLs that point to a development environment: a[href*="dev."]

Other features

PropDefaultDescription
customChecks-To use custom checks, use the `new` keyword with the `CustomChecks` class name. E.g. `customChecks: new CustomChecks`
nonConsecutiveHeadingIsErrortrueBoolean. 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.
flagLongHeadingstrueBoolean. Flag headings longer than 170 characters. This is not a WCAG criterion.
showGoodLinkButtontrueBoolean. Show "Good" annotations on links with an accessible name that was defined with an aria-label or aria-labelledby attribute. Sometimes content authors wonder why some "learn more" links are not flagged by Sa11y.
detectSPAroutingfalseBoolean. Detects URL changes and re-checks the page. This prop is intended for the bookmarklet to improve usability when testing single page applications (SPA).
doNotRun''Using a comma seperated list, provide selectors to unique pages where you do not want Sa11y to check.

Readability module

The readability module is based on Flesch reading ease.

PropDefaultDescription
readabilityPlugintrueBoolean. Set to false to turn off and hide Readability check from the Settings panel.
readabilityRoot'body'Target area for readability check. For example, pass main for main content area. Accepts a single selector only.
readabilityLang'en'Default is English. Currently supports English (en), French (fr), German (de), Spanish (sp), Italian (it), and Dutch (nl).
readabilityIgnore''Ignore specific content from readability check. Hard default excludes list (<li>) tags within navigation landmarks.

Toggleable rulesets in Settings panel

PropDefaultDescription
contrastPlugintrueSet to false to turn off and hide contrast check from Settings panel.
formLabelsPlugintrueSet to false to turn off and hide Form labels check from Settings panel.
linksAdvancedPlugintrueSet to false to turn off and hide Links (Advanced) check from Settings panel.

Quality assurance module

PropDefaultDescription
badLinksQAtrueRelated to linksToFlag prop.
strongItalicsQAtrueFlags entire paragraphs that are bold or italicized.
pdfQAtrueWarning about PDF content.
langQAtrueError if page language is not set.
blockquotesQAtrueWarning if blockquote suspiciously resembles a heading.
tablesQAtrueVarious errors about innaccessible HTML tables.
allCapsQAtrueWarning about use of ALL CAPS. Note: Sometimes this check can be problematic because of regex usage. Set to false if problematic.
fakeHeadingsQAtrueWarning about bolded text that suspiciously resembles a heading. Uses regex.
fakeListQAtrueWarning about suspiciously formatted content that should be a semantic list.
duplicateIdQAtrueError if duplicate id exist on the page.
underlinedTextQAtrueWarning for <u>underlined<u> text.
pageTitleQAtrueError if meta page <title> is missing or empty.

Embedded content (iFrames) module

PropDefaultDescription
embeddedContentAlltrueSet to false to ignore all iFrames.
embeddedContentAudiotrueWarning about audio content and transcripts.
embeddedContentVideotrueWarning about video content and captions.
embeddedContentTwittertrueWarning about endless Twitter widgets.
embeddedContentDataViztrueWarning about data visualizations.
embeddedContentTitlestrueWarning about iFrame missing a descriptive title or accessible name.
embeddedContentGeneraltrueGeneral warning about unknown iFrame content.
videoContent'video, youtube.com, vimeo.com, yuja.com, panopto.com'Common video players.
audioContent'audio, soundcloud.com, simplecast.com, podbean.com, buzzsprout.com, blubrry.com, transistor.fm, fusebox.fm, libsyn.com'Common podcast widgets or audio players.
dataVizContent'datastudio.google.com, tableau'Common data visualization widgets.

Feedback

Provide feedback on props via GitHub or Report a bug.