iOS Accessibility in SwiftUI Tutorial Part 1: Getting Started

In this article, you’ll fix the accessibility of a SwiftUI master-detail app with various types of images that need more informative labels. By Audrey Tam.

Leave a rating/review
Download materials
Save for later

Accessibility matters. You already know this, or you wouldn’t be reading this article. ;] 15-20% of people live with some form of disability, and another 5% experience short-term disability. They’re all potential customers of your app: They want to use your app, you want to make sure they can use your app, and SwiftUI is here to help.

Most app UIs are very visual experiences, so most accessibility work focuses on VoiceOver — a screen reader that lets people with low to no vision use Apple devices without needing to see their screens. VoiceOver reads out information to users about your app’s UI elements. It’s up to you to make sure this information helps users interact efficiently with your app.

In this tutorial, you’ll fix the accessibility of a simple SwiftUI master-detail app with various types of images that need more informative labels. You’ll learn that SwiftUI elements are accessible by default, and how this helps you.

Note: This tutorial is about accessibility in SwiftUI apps. For UIKit apps, check out our tutorial iOS Accessibility: Getting Started. It has some cool videos.

In particular, you’ll learn how to:

  • Improve your app’s accessible UI with labels that provide context for images, emoji, system images and map view annotations.
  • Use the SwiftUI Accessibility API attributes.
  • Inspect your app with Xcode’s Accessibility Inspector and its VoiceOver simulator.
  • Navigate your app with VoiceOver on an iOS device.

Apple’s investing a lot of effort in helping you improve the accessibility of your apps. With SwiftUI, it’s easier than ever before. The future is accessible, and you can help make it happen!

Note: This tutorial assumes you’re comfortable with using Xcode to develop iOS apps. You need Xcode 11 to use SwiftUI. To see the SwiftUI preview, you need macOS 10.15. Some familiarity with SwiftUI will be helpful: Check out our tutorial SwiftUI: Getting Started if you need a refresher. You’ll also need an iOS device to hear the effect of some of your work.

Getting Started

Get started by downloading the materials for this tutorial — you can find the link at the top or bottom of this article. Open the PublicArt project in the begin folder. This is based on the project from SwiftUI Tutorial: Navigation.

Build and run the app in an iPhone Simulator. You get a list of public artworks in Honolulu:

Artworks list view

Some have a reaction emoji, which indicates the user has already visited them. There’s a Hide Visited toggle in the navigation bar, to show only artworks that the user hasn’t visited.

Long-press an item to see a context menu where the user can select a reaction emoji:

Reaction emoji context menu

Tap anywhere to close the context menu, then tap an item to show its detail view with image, title, location, artist and description of the artwork. Depending on the length of the title, the Back button is Artworks, Back or just an arrow.

Detail view: Prince Kuhio

Tap the small map pin icon next to the location, to show a map with a pin at the location:

Map centered at Kuhio Beach

Tap Done to dismiss the map, then tap the Back button or arrow to return to the list.

Note: After returning to the list view, tapping the same item doesn’t load its detail view. This is a NavigationLink bug in Simulator and doesn’t happen when you run this app on a device.

Accessibility in SwiftUI

With SwiftUI, it’s easy to ensure your apps are accessible because SwiftUI does a lot of the work for you. SwiftUI elements support Dynamic Type and are accessible by default. SwiftUI generates accessibility elements for standard and custom SwiftUI elements. Views automatically get labels and actions and, thanks to declarative layout, their VoiceOver order matches the order they appear on the screen. SwiftUI tracks changes to views and sends notifications to keep VoiceOver up to date on visual changes in your app.

Note: You can watch notifications by opening Windows▸Show Notifications in the Accessibility Inspector you’ll use throughout this article.

When the accessibility built into SwiftUI doesn’t provide the right information in the right order, you’ll use the SwiftUI Accessibility API to make your accessible elements understandable, interactable and navigable:

  • Understandable: In this first part of this tutorial, you’ll learn what SwiftUI generates for VoiceOver from SwiftUI element initializers. Then, to clarify or add context to accessible elements, you’ll override the generated default labels. In Part 2, you’ll customize the accessibility labels and values, hiding elements that provide redundant information, and moving some information to hints that the user doesn’t have to listen to.
  • Interactable: Try to give your accessible elements appropriate default actions, and create custom actions to simplify interaction for users of assistive technology. When VoiceOver is working correctly, it lets users swipe down to access custom actions like context menus.
  • Navigable: In Part 2, you’ll change the order that VoiceOver visits elements, and you’ll group elements to reduce the number of steps and speed up navigation for VoiceOver users.

The amount of work for each accessible element could be as little as a few words or lines of code. Or you might need to refactor or add code, or even change a navigation link into a modal sheet.

Most of the time, you’ll add accessibility to your app without changing its appearance and behavior for users who aren’t using VoiceOver. But sometimes, something you do for VoiceOver will inspire an improvement to your visual UI.

Using the Accessibility Inspector

Now try out Xcode’s Accessibility Inspector on PublicArt running in the simulator. The app doesn’t have to be running in Xcode.

To start, in the Xcode menu, select Xcode▸Open Developer Tool▸Accessibility Inspector.

Xcode: Open accessibility inspector

When the window appears, select your simulator in the target selection menu, and select the Inspection tab: It’s the first of the set of three buttons:

Target simulator. Select Inspection tab.

Note: Sadly, Accessibility Inspector’s target menu doesn’t include SwiftUI preview. The other tabs are Audit and Settings. You’ll use Audit later in this article, and Settings in Part 3.

The single button next to the target field turns on the Inspection Pointer or Inspection-follows-point — Option-Space toggles it. When it’s working, you just point the cursor at a UI element to highlight it and view its accessibility information. At the time of writing this article with Xcode 11.3, this doesn’t work. Instead, click the Fast-Forward button to advance highlighting to the next element.

First, point the cursor or click Fast-Forward to highlight the Hide Visited toggle in the navigation bar. Its accessibility information appears in the inspector:

Highlight Hide Visited toggle: Point cursor or click Fast-Forward

There are four sections: Basic, Actions, Element and Hierarchy. If necessary, click Show for the Basic and Actions sections. The Basic information also appears in the top Quicklook area: It consists of the Label Hide Visited, the Value 0 and the Trait Button. And there’s an Activate: Perform button in the Actions section.