Single Page Applications

Owned by Kim Collins (Unlicensed)
Last updated: May 10, 2022 by Joseph McLarty
3 min read

There are several important considerations to keep in mind for developers when they choose to create a single page application (SPA). This document aims to provide guidance on how to create an accessible single page application user experience - outlining best practices and common accessibility challenges found in SPAs.

What is a “page”?

Regardless of the technology used, if a user experiences a view as a unique page, it should behave as a unique page. This means that, like standalone HTML pages, each “page” should:

  • Have a unique <title> element 

  • Have a unique <h1>

  • Have a unique, navigable url

  • Announce the page title when the view loads

  • Have focus set to a consistent place (e.g., always on the outermost parent element of the page, or the <h1>, or another element, depending on the page content).

Navigating application views

It's important to make sure that the expected ways of navigating the web are maintained in a single page application. 

  • Web navigation conventions like history states and use of the browser back button (or Alt + Left Arrow, in Chrome) should continue to function

  • New views across “pages” should all have unique URLs

  • New views should also have unique HTML <title>s  

Page Titles

Page titles are important to orient users to page content.

When screen reader users navigate to a new page, the page title is announced, informing the user of the context of the page and that their navigation action has been successful. All users can identify the page in a set of browser tabs by the page title in the tab.

Page titles should be unique for each view that the user experiences as a page. 

In a single page application, this means that as each new view is loaded:

  1. The <title> element is updated

  2. A mechanism is provided to announce the new page title to screen reader users.

Changing the value of the <title> element dynamically does not trigger an announcement to screen reader users. There are several different approaches to achieve this announcement. Among the easiest approaches is setting programmatic focus to the unique <h1> of the page when the view loads, so the content of the <h1> is announced. Make sure the <h1> has a tabindex value of -1, so it can receive programmatic focus, but will not be in the tab order.

Another approach is creating an aria-live region in the page and updating its content when a new view is loaded and the page title changes.

Focus Management

When a user loads your single page application for the first time in a session, programmatic focus should not be set. This allows the user to discover the page naturally - the page title will be announced, and the user can sequentially encounter a Skip to Content link, header and navigation content.

On subsequent view loads within a single session, you will need to choose a consistent element to set focus to. The <h1> can be a good option (as discussed above in the Page Titles section), as it will help orient the user to the current view. 

If your application uses a combination of SPA and standalone HTML pages, ensure the focus on page/view load is consistent (e.g. if the standalone pages do not have focus set, consider setting focus to the <body> or the outermost parent element within the <body> on your SPA pages so the experience will be consistent).

tabindex

The tabindex attribute is critical when managing focus programmatically. 

The value of the tabindex attribute should be either -1 or 0. Do not set a tabindex above 0.

  • tabindex="-1" means the element can receive focus programmatically, but is not in the tab order. A user will not land on the element when navigating a page using the tab key.

  • tabindex="0" means the element can receive focus programmatically and is in the tab order. A tabindex of 0 is appropriate for custom interactive elements.

For non-interactive elements that should receive programmatic focus, like the <h1>, the value of the tabindex attribute should be -1.

Advanced focus management

Special consideration will need to be made for managing focus when deleting content or modifying content in an application. For example:

  • Performing an action that removes the currently focused element from the DOM

  • Adding a selection to a list

For information on advanced focus management techniques and advice about focus management and application lifecycle, explore these resources:

Check the Focus page for more details. 

Contextual Announcements

Screen reader users need to be kept informed about changes to the content or context of the page. Providing feedback to user input is critical to a screen reader user’s ability to use an application.

For messages that provide information but do not require a user’s input, use a <div> with aria-live="polite" and role="status". This ensures users are kept informed, but their keyboard focus is not changed and their task is not interrupted. Consider creating a component to handle this kind of messaging.

Note

Content in a live region will only be announced if the region is present in the DOM before the content in the live region changes. See Live Regions for more information about how aria-live works.