How to set custom accessibility labels and hints

Paul Hudson @twostraws May 30th 2025

Updated for Xcode 16.4

Improved in iOS 18

SwiftUI does a great job of providing sensible default accessibility labels for text, images, and many other built-in views, but very often you'll want to customize this yourself using the accessibilityLabel() and accessibilityHint() modifiers.

Important: Your accessibility labels are read immediately by VoiceOver, and so should be kept short and to the point. Accessibility hints are bonus text that get read after a short delay, and can provide extra information beyond the label.

For example, we could use accessibilityLabel() and accessibilityHint() together to provide better context on what your view means:

Button("Add", systemName: "person.crop.circle") {
    print("Adding friend…)
}
.accessibilityLabel("Add to group")
.accessibilityHint("Add Jess to the Bridgerton Fans chat group.")

If you're able to target iOS 18 and later, there is an additional variant of accessibilityLabel() that is very helpful: we can provide it with a closure to customize whatever is SwiftUI's default label, allowing us to add to an existing description.

For example, the code below will read SwiftUI's default label for the text, but add the word "Warning" before it to reflect the fact that the text is bold and red:

Text("This is an important message")
    .fontWeight(.bold)
    .foregroundStyle(.red)
    .accessibilityLabel { label in
        Text("Warning:")
        label
    }

How to set custom accessibility labels and hints

Similar solutions…