Support for iOS accessibility features

Compose Multiplatform accessibility support allows people with disabilities to interact with the Compose Multiplatform UI as comfortably as with the native iOS UI:

Screen readers and VoiceOver can access the content of the Compose Multiplatform UI.
The Compose Multiplatform UI supports the same gestures as the native iOS UI for navigation and interaction.

This is possible because semantics data produced by Compose APIs is now mapped to native objects and properties that are consumed by iOS Accessibility Services. For most interfaces built with Material widgets, this should happen automatically.

You can also use this semantic data in testing and other automation: properties such as testTag will correctly map to native accessibility properties such as accessibilityIdentifier. This makes semantic data from Compose Multiplatform available to Accessibility Services and XCTest framework.

The Compose accessibility API doesn't currently support:

Live regions (announcements about content changes in a specific area).
UIKit elements inside Compose Multiplatform UI.

iOS accessibility support is in the early stages of development. If you have trouble with this feature, we would appreciate your feedback in the #compose-ios Slack channel or as an issue in the Compose Multiplatform GitHub repo.

Customize synchronization of the accessibility tree

With default settings:

The iOS accessibility tree is synchronized with the UI only when Accessibility Services are running.
Synchronization events are not logged.

You can customize these settings with the new Compose Multiplatform API.

Choose the tree synchronization option

To debug and test events and interactions, you can change the synchronization mode to:

Never synchronize the tree with UI, for example, to temporarily disable accessibility mapping.
Always synchronize the tree so that it is rewritten every time the UI updates to test the accessibility integration thoroughly.

An example of enabling the option to always synchronize the accessibility tree:

ComposeUIViewController(configure = {
    accessibilitySyncOptions = AccessibilitySyncOptions.Always(debugLogger = null)
}) {
    // your @Composable content
}

The AccessibilitySyncOptions class contains all available options:

// package androidx.compose.ui.platform

@ExperimentalComposeApi
sealed class AccessibilitySyncOptions {
    
    // Option to never synchronize the accessibility tree
    object Never: AccessibilitySyncOptions

    // Option to synchronize the tree only when Accessibility Services are running
    //
    // You can include an AccessibilityDebugLogger to log interactions and tree syncing events
    class WhenRequiredByAccessibilityServices(debugLogger: AccessibilityDebugLogger?)

    // Option to always synchronize the accessibility tree
    //
    // You can include an AccessibilityDebugLogger to log interactions and tree syncing events
    class Always(debugLogger: AccessibilityDebugLogger?)
}

Implement the logging interface

You can implement the AccessibilityDebugLogger interface to write custom messages to an output of your choosing:

ComposeUIViewController(configure = {
    accessibilitySyncOptions = AccessibilitySyncOptions.WhenRequiredByAccessibilityServices(object: AccessibilityDebugLogger {
         override fun log(message: Any?) {
             if (message == null) {
                 println()
             } else { 
                 println("[a11y]: $message") 
             } 
         } 
    })
}) {
    // your @Composable content
}

What's next?

Now that you're up to speed with iOS accessibility support in Compose Multiplatform:

Try out the project generated by the Kotlin Multiplatform wizard in your usual iOS accessibility workflow.
Learn about resource qualifiers that will be helpful when adapting a Compose Multiplatform UI to a particular situation.

Last modified: 14 March 2024