Accessibility 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()]
});

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}'
}