React Native A11y Order

React Native A11y Order Library: Advanced control of screen reader order.

Setting the right reading order can be a challenge, but there is a way to do it. The react-native-a11y-order is a native-first library designed to solve problems with the ordering of screen readers on both Android and iOS platforms.

iOS reader	Android reader

• Bridgeless
• New architecture
• Backward compatibility

Installation

npm install react-native-a11y-order

yarn add react-native-a11y-order

For React Native Below Version 0.74.x

If you are using a React Native version below 0.74.x with NewArch enabled, you may encounter an error with component registration. To resolve this issue, add the following code to your ios/Podfile file.

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)']
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] << "RCT_VIEW_MANAGER_ENABLED=1"
    end
  end
end

You can also use version [email protected]. Version 0.3.0 is released solely to support React Native versions 0.79.x to 0.80.x.

Usage

A11y.Order, A11y.Index

There is always a question about how to set the focus order for a screen reader in React Native. A11y.Order and A11y.Index are designed to assist with this task. A11y.Order is a container component that defines an ordering group, while A11y.Index is a wrapper component that helps define a position within the order.

To illustrate, let's look at an example:

import { A11y } from 'react-native-a11y-order';

// ...

export default function App() {
  return (
    <View style={styles.container}>
      <A11y.Order>
        <A11y.Index index={1}>
          <Text style={styles.font}>
            First
          </Text>
        </A11y.Index>
        <A11y.Index index={3}>
          <Text style={styles.font}>
            Third
          </Text>
        </A11y.Index>
        <A11y.Index index={2}>
          <Text style={styles.font}>
            Second
          </Text>
        </A11y.Index>
      </A11y.Order>
      <Text style={styles.font}>Fourth</Text>
      <Text style={styles.font}>Fifth</Text>
      <Text style={styles.font}>Sixth</Text>
    </View>
  );
}

Additionally, for dynamic interaction scenarios, setting focus programmatically can be very useful. This can be achieved using the focus command via a component ref.

import { A11y, IndexCommands } from 'react-native-a11y-order';

// ...

export default function App() {
  const ref = React.useRef<IndexCommands>(null);

  return (
    <View style={styles.container}>
      <A11y.Order>
        <A11y.Index ref={ref} index={1}>
          <Text style={styles.font}>
            First
          </Text>
        </A11y.Index>
      </A11y.Order>
      <Button onPress={() => ref.current?.focus()}>
    </View>
  );
}

Important: Order between elements and order between groups Android and iOS have different native implementations, which can result in varying behavior across platforms. This package was originally developed to define a logical order among individual accessible elements. However, there are situations where it's necessary to set an order for groups of elements. While this is relatively simple to achieve on iOS, it can be more complicated on Android.

To resolve this on Android, you can define a View with the accessible property and use the accessibleLabel attribute to describe the group.

For example:

<View style={{flex: 1, position: 'relative'}}>
  <A11y.Order style={{flex: 1}}>
    <A11y.Index index={1}>
      <View
        accessible={Platform.OS = 'android'} // It helps to create a group to maintain the correct order for Android.
        accessibilityLabel="Header Group" 
      >
        ...
      </View>
    </A11y.Index>
    <A11y.Index
      index={2} // For a single element, we don't need anything extra.
      style={{ position: "absolute", right: 20, bottom: 50, zIndex: 1}}
    >
      <Button title="Chat" />
    </A11y.Index>
    <A11y.Index 
      index={3} // We don't need a group for ScrollView; it creates its own scope.
    >
      <ScrollView>
        <View
          accessible
          accessibilityLabel="Mindaro"
          style={{width: '100%', height: 200, backgroundColor: '#CEEC97'}}
        />
        <View
          accessible
          accessibilityLabel="Peach"
          style={{width: '100%', height: 200, backgroundColor: '#F4B393'}}
        />
      </ScrollView>
    </A11y.Index>
  </A11y.Order>
</View>

Additionally, it would be better to wrap every component inside A11y.Order with A11y.Index; the order of unwrapped components is not predictable.

A11y.Index Props:

Props	Description
ViewProps	Default View props including style, testID, etc
index	number, position in order
ref: focus	focus command for setting accessibility focus

A11y.Order Props:

Props	Description
ViewProps	Default View props includin style, testID, etc

A11y.Group

A11y.Group can be used to enhance the experience of screen readers navigating through ScrollView or FlatList with the horizontal property enabled. You can skip this if you are using the new architecture; however, it is the best for applications that have not yet migrated.

View	A11y.Group

import { A11y, IndexCommands } from 'react-native-a11y-order';

// ...

export default function App() {
  return (
    <ScrollView
      style={styles.slider}
      contentContainerStyle={styles.sliderContainer}
      horizontal
    >
      <A11y.Group style={styles.slide}>
        <View>
          <Text>Title: 1</Text>
        </View>
        <View>
          <Text>Description: 1</Text>
        </View>
      </A11y.Group>
      <A11y.Group style={styles.slide}>
        <View>
          <Text>Title: 2</Text>
        </View>
        <View>
          <Text>Description: 2</Text>
        </View>
      </A11y.Group>
    </ScrollView>
  );
}

Props	Description
ViewProps	Default View props including style, testID, etc

Migration

Why?

The previous versions of this library used native modules to update order, but in a world with Fabric components and new architecture, there is no visible future for managing native components via modules or findNodeHandler.

I thought a lot about retaining the previous API for support and compatibility, but after investigation, it was decided to deprecate the 'old' API and remove it in future releases.

The new approach is better: we no longer need to manage refs, worry about attaching nodes to the screen, and it works natively. Additionally, this new approach follows the React Native concept, which will make it easier to support in the future (hello there: bridgeless).

1. Update: A11yOrder to A11y.Order

  Previous: <A11yOrder a11yOrder={a11yOrder}>
  Now: <A11y.Order>

2. Wrap components in A11y.Index

  Previous: <Text style={styles.font} ref={refs[0]}>
    First
  </Text>
  Now: <A11y.Index index={1}>
    <Text style={styles.font} ref={refs[0]}>
      First
    </Text>
  </A11y.Index>

3. Remove unnecessary refs

<A11y.Index index={1}>
  <Text style={styles.font}>
    First
  </Text>
</A11y.Index>

4. Remove deprecated hooks and utilities: useFocusOrder, useDynamicFocusOrder, useA11yOrderManager.

That's all. The index changes, removals, etc., should work out of the box.

Roadmap

• Add order links for better focus control
• Add preferred focus logic for focus "return" functionality
• Refactor and optimize performance
• Add documentation and descriptive examples

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library