Skip to main content

Workarounds

There are some techniques that are do not follow ARIA/WCAG or are workarounds to improve accessibility.

These are not recommended practices but they "get the job done".

Overriding Visible Text

An aria-label only works for interactive elements. So, HTML like this will unfortunately be announced as "3" by the screen reader:

<ion-label aria-label="3 bedrooms">3</ion-label>

You can have the screen reader announce something different from the visible text using the following HTML:

<div role="text" aria-label="3 bedrooms">
  <ion-label aria-hidden="true">3</ion-label>
</div>
warning

role="text" is not a recognised aria attribute, however it is implemented by Voice Over in iOS and TalkBack in Android.

A screen reader should read the visible text, so in the above example you should make the visible text 3 bedrooms instead of 3. You would only use this technique if your UI design takes precedence over accessibility design.

Reading Formatted Text

Voice Over will break apart text that contains formatting. For example:

<ion-text>I like <strong>big</strong> brown <em>bears</em>.</ion-text>

The above text will be read as: "I like. Big. Brown. Bears.".

To ensure that Voice Over reads this sentence as "I like big brown bears." we can set role="text":

<ion-text role="text">I like <strong>big</strong> brown <em>bears</em>.</ion-text>
warning

role="text" is not a recognised aria attribute, however it is implemented by Voice Over in iOS and TalkBack in Android.

Page Titles

TalkBack on Android will attempt to announce the page's title. You can use this to describe the page the user is on.

In an Angular application you can set the page title in your routing. For example in app-routes.ts or app-routing-module.ts:

{
    path: 'intro',
    title: 'Introduction',
    loadComponent:...
  },

You can also set the title programatically in Angular:

import {Title} from "@angular/platform-browser";

....

constructor(private title:Title) {
  this.title.setTitle("Introduction Part 1 of 3");
}

A vanilla javascript alternative may be:

document.title = 'Introduction';
note

TalkBack will read the document title followed by "WebView". There is no known option to change this text.

First Read Element on Routing

The screen reader will select the first element it wants to read when you route between pages.

On Android this will be the page itself and after swiping right TalkBack will select a focusable element in the top left of the screen.

On iOS the first element may appear to be random but it chooses an element close to where you have pressed before. This behavior is an undesirable quirk of VoiceOver.

Ionic Framework version 8 introduces focusManagerPriority as a solution to ensure that the desired element is focused when the route changes.

To use this feature you can modify your Ionic config to set focusManagerPriority. For example in main.ts in an Angular application:

provideIonicAngular({ focusManagerPriority: ['heading', 'content'] }),

Now, whenever the route changes the focus will go the first heading element.

note

focusManagerPriority is currently marked as Experimental. Be sure to report any issues you may encounter.