How to set heading levels for text

Paul Hudson @twostraws May 30th 2025

Updated for Xcode 16.4

SwiftUI’s accessibilityHeading() modifier allows us to set a heading level for a piece of text, which makes it much easier to navigate through lots of text for folks using VoiceOver.

There are six heading levels available, from .h1 through to .h6, and each one tells the system how important this heading is so that it can be read or navigated to appropriately. It is not attached to the font size or style, so you should combine the two as appropriate.

Important: You must combine this modifier with .accessibilityAddTraits(.isHeader) in order for VoiceOver to detect your headings.

For example, this code uses both top-level .h1 headings and second-level .h2 headings, along with appropriate fonts:

VStack { Text("Hacking with Swift books") .font(.title) .accessibilityAddTraits(.isHeader) .accessibilityHeading(.h1) .padding(.bottom) Text("Testing Swift") .font(.headline) .accessibilityAddTraits(.isHeader) .accessibilityHeading(.h2) Text("If you're serious about writing great code, you need to be serious about writing great tests. Testing Swift is designed to guide you through unit tests, UI tests, TDD, and much more!") .padding(.bottom) Text("Swift Interview Challenges") .font(.headline) .accessibilityAddTraits(.isHeader) .accessibilityHeading(.h2) Text("Work through real Swift coding problems that help strengthen your skills – perfect for finding and filling holes in your Swift knowledge, and preparing for iOS interviews.") }

That code specifically marks the headings, which means VoiceOver users can skip through to the parts they care about – they might skip through the names of 10 different books before reading the text below.

If you're not familiar with VoiceOver, you can headings out by saying "Enable VoiceOver" to Siri. Once that's done, use two fingers to make a rotation gesture on your screen, which will bring up the VoiceOver rotor – a way of selecting the mode VoiceOver is using.

If you repeat that gesture, you'll move through the default rotor options, which includes being able to read individual characters, individual words, adjust the speaking rate, and so on. One of those options is headings, and once that's activated you can swipe up and down to move through headings, skipping things that aren't headings completely.

Note: When you're done, you can tell Siri to "Disable VoiceOver."

How to set heading levels for text

Similar solutions…