@swup/a11y-plugin

Enhanced accessibility for swup-powered sites

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@swup/a11y-plugin
112.1.0a month ago2 years agoMinified + gzip package size for @swup/a11y-plugin in KB

Readme

Swup A11y Plugin
by daun
Enhance the accessibility of your swup
-powered sites.
Loading new content via AJAX is great UX for most users, but comes with serious shortcomings for screen reader users. We can improve the experience for everybody if we:
  • Announce page visits to screenreaders by reading the new page title
  • Focus the main content area after swapping out the content

That's exactly what this plugin does.

Installation

This plugin can be installed with npm
npm install @swup/a11y-plugin

and included with import
import SwupA11yPlugin from '@swup/a11y-plugin';

or included from the dist folder
<script src="./dist/SwupA11yPlugin.js"></script>

Usage

To run this plugin, include an instance in the swup options.
const swup = new Swup({
  plugins: [new SwupA11yPlugin()]
});

Markup

The plugin should work out of the box if you use proper semantic markup for your content, i.e. main for your content area and h1 or h2 for your headings. See the options below for customizing what elements to look for.
<header>
  Logo
</header>
<main> <!-- will be focussed -->
  <h1>Page Title</h1> <!-- will be announced -->
  <p>Lorem ipsum dolor sit amet</p>
</main>

Styling

Browsers will display a visible outline around the main content area when it receives focus after navigation. Make sure to remove the outline in your CSS if that isn't the desired behavior.
main[tabindex="-1"] {
  outline: none;
}

Options

All options with their default values:
{
  contentSelector: 'main',
  headingSelector: 'h1, h2, [role=heading]',
  announcementTemplate: 'Navigated to: {title}',
  urlTemplate: 'New page at {url}'
}

contentSelector

The selector for matching the main content area of the page.
This area will receive focus after a new page was loaded.

headingSelector

The selector for finding headings inside the main content area.
The first heading's content will be read to screen readers after a new page was loaded.

announcementTemplate

How to announce the new page title.

urlTemplate

How to announce the new page url.
Only used as fallback if neither a title tag nor a heading were found.