Custom checks
You can extend Sa11y beyond checking for accessibility issues. For example, create checks that promote better usability, or encourage proper use of components and web style guidelines. All custom checks should be created within /src/sa11y-custom-checks.js
.
How to create a custom check
You can create custom checks with just a few lines of JavaScript. There are two types of annotations you create: Button annotations appended at the source of the issue, and full page issues that are displayed within Sa11y's panel. There are several utilities functions and elements you can use.
Simply populate the results
object to flag an issue.
Annotation
- element - Issue element (Element)
- type - Type of issue: Error, Warning, or Pass. (String)
- content - Tooltip message. (String)
- inline - Display annotation inline with text. (Boolean)
- position - Where to insert annotation. View
insertAdjacentHTML()
parameters. (String) - dismiss - A string that uniquely identifies the found issue used for all warnings.
- All warnings must have have a dismiss key. Errors cannot be dismissed.
- It's very important that the key is unique. It's recommended to pass the element's inner text for example. Use the
Utils.prepareDismissal
utility function to generate a key.
Page Issue
Simply pass a type and content to create a Page Issue that's displayed in the main panel.
- type - Type of issue: Error, Warning, or Pass. (String)
- content - Issue message. (String)
Recipes
Both recipes below are included in sa11y-custom-checks.js for reference.
Overusing a component on a page
The example detects if more than one announcement is detected on a page, although it could be easily extended to anything. Too many slideshows? Too many accordions? You name it.
const $checkAnnouncement = find('.sa11y-announcement-component', 'root');
if ($checkAnnouncement.length > 1) {
for (let i = 1; i < $checkAnnouncement.length; i++) {
const key = Utils.prepareDismissal($checkAnnouncement[i].textContent);
results.push({
element: $checkAnnouncement[i],
type: Constants.Global.WARNING,
content: C.ANNOUNCEMENT_MESSAGE,
inline: false,
position: 'beforebegin',
dismiss: key,
});
}
}
Demo
Accordion component contains a form
Forms nested within accordion components can be problematic if it uses server-sided validation. The page will reload, and the accordion usually returns back to its closed state. This is problematic for everyone.
const $checkAccordions = find('.sa11y-accordion-example', 'root');
$checkAccordions.forEach(($el) => {
const checkForm = $el.querySelector('form');
if (!!checkForm && checkForm.length) {
results.push({
element: $el,
type: Constants.Global.ERROR,
content: C.ACCORDION_FORM_MESSAGE,
inline: false,
position: 'beforebegin',
});
}
});
Demo
Add or suggest a recipe
Share your recipe on GitHub.