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:
- Fork or download the latest release
- Be sure you have node installed and up to date.
- Execute
npm install
- In a terminal execute:
npm run serve
. Then openhttp://localhost:8080/docs/demo/en/
in your browser.
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.