Install

Sa11y is a framework-agnostic JavaScript plugin. It's made with vanilla JavaScript and CSS, and its only dependency is Tippy.js - a highly customizable tooltip library that features a positioning system.

To install on your website, insert Sa11y right before the closing </body> tag. Include both Tippy.js and Popper.js before Sa11y. Sa11y consists of four files:

  • sa11y.css - The main stylesheet. Should be included in the <head> of the document (if possible).
  • lang/en.js - All text strings and tooltip messages. View supported languages.
  • Optional sa11y-custom-checks.js - Any custom checks creataed by you.
  • sa11y.js - Contains all logic.

Demo and local development

A light server for development is included. Any change inside /src folder files will trigger the build process for the files and will reload the page with the new changes. To use this environment:

  1. Fork or download the latest release
  2. Be sure you have node installed and up to date.
  3. Execute npm install
  4. In a terminal execute: npm run serve. Then open http://localhost:8080/docs/demo/en/ in your browser.

View demo

Example installation (modules)

<!-- Stylesheet -->
<link rel="stylesheet" href="sa11y.css"/>

<script type="module">
  import { Sa11y, Lang } from '../assets/js/sa11y.esm.js';
  import Sa11yLangEn from '../assets/js/lang/en.js';

  // Optional: Custom checks
  import CustomChecks from '../assets/js/sa11y-custom-checks.esm.js';

  // Set translations
  Lang.addI18n(Sa11yLangEn.strings);

  // Instantiate
  const sa11y = new Sa11y({
    customChecks: new CustomChecks, // Optional
    checkRoot: "body",
  });
</script>

Example installation (regular script)

<!-- Stylesheet -->
<link rel="stylesheet" href="sa11y.css"/>

<!-- Sa11y (fork the latest code from GitHub) -->
<script src="/dist/js/sa11y.umd.min.js"></script>
<script src="/dist/js/lang/en.umd.js"></script>

<!-- Optional: Custom checks -->
<script src="/dist/js/sa11y-custom-checks.umd.min.js"></script>

<!-- Instantiate-->
<script>
  Sa11y.Lang.addI18n(Sa11yLangEn.strings);
  const sa11y = new Sa11y.Sa11y({
    customChecks: new CustomChecks, // Optional
    checkRoot: "body",
  });
</script>

CDN via jsDelivr

The CDN link below is the latest and greatest (stable) release of Sa11y. Current version: @2.3.2

<!-- Stylesheet -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/ryersondmp/sa11y@2.3.2/dist/css/sa11y.min.css"/>

<!-- Script -->
<script src="https://cdn.jsdelivr.net/combine/gh/ryersondmp/sa11y@2.3.2/dist/js/lang/en.umd.js,gh/ryersondmp/sa11y@2.3.2/dist/js/sa11y.umd.min.js"></script>

<!-- Instantiate-->
<script>
  Sa11y.Lang.addI18n(Sa11yLangEn.strings);
  const sa11y = new Sa11y.Sa11y({
    customChecks: new CustomChecks, // Optional
    checkRoot: "body",
  });
</script>

CDN with automatic updates

The CDN link below automatically fetches the @latest stable release. This is essentially how the bookmarklet is served.

Warning: This is not recommended for production... or you know, use at your own risk. 😬

<!-- Stylesheet -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/ryersondmp/sa11y@latest/dist/css/sa11y.min.css"/>

<!-- Script -->
<script src="https://cdn.jsdelivr.net/combine/gh/ryersondmp/sa11y@latest/dist/js/lang/en.umd.js,gh/ryersondmp/sa11y@latest/dist/js/sa11y.umd.min.js"></script>

<!-- Instantiate-->
<script>
  Sa11y.Lang.addI18n(Sa11yLangEn.strings);
  const sa11y = new Sa11y.Sa11y({
    customChecks: new CustomChecks, // Optional
    checkRoot: "body",
  });
</script>

Languages

Sa11y has been translated into: French (fr-ca), Polish (pl), and Ukrainian (ua). You can view the translations on GitHub.

Want to help translate or improve Sa11y? Consider contributing! Translations may either be contributed back to the repository with a pull request on GitHub, or translated files can be returned to: adam.chaboryk@ryerson.ca

CDN

To utilize CDN links above, simply replace lang/en.umd.js with preferred language code.

Readability

Sa11y's readability feature is based on Flesch reading-ease test (Wikipedia). At this time, Sa11y only supports English, Dutch, Italian, French, German, and Spanish.

Accessibility note about Tippy.js

Sa11y appends tooltips to the end of the body by default to ensure tooltips do not get hidden by conflicting CSS styling. If you customize the tooltips to include interactive content, please read Tippy.js documentation on creating accessible interactive tooltips for keyboard users.