Accessibility

You.i React Native allows app developers to support screen reader (text-to-speech) functionality using various RN props, methods, and modules. This topic covers the supported props, methods, modules, gesture support, screen reader settings, and best practices for creating accessible apps.

We support screen reader functionality for the following target platforms:

Refer to RNSampleApp, located at youiengine/<version>/samples/RNSampleApp, for an example of how accessibility is implemented with You.i React Native. In general, to know more about the accessibility feature in React Native, see Facebook’s Accessibility topic.

Before we begin, we should define two terms used in this topic: accessibility focus and navigation focus.

Accessibility focus is the focus you get on an element in your app when you tap or use screen reading through the accessibility feature, irrespective of what device the app is running on.
Navigation focus on 10ft devices allows users to navigate between different elements or screens in an app.

Supported props

The following props are supported in You.i React Native for accessibility:

Props Supported	For Which Components	Details	Facebook RN Docs
`accessible`	Button, ButtonRef, Image, ImageRef, Text, TextInput, TextInputRef, TextRef, TouchableHighlight, TouchableOpacity, TouchableWithoutFeedback, View, and ViewRef	When `true`, indicates that the view is an accessibility element.	accessible
`accessibilityActions`	View and ViewRef	Allows an assistive technology to programmatically invoke the actions of a component.	accessibilityActions
`accessibilityHint`	Text, TextRef, TouchableWithoutFeedback, View, and ViewRef	Helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.	accessibilityHint
`accessibilityLabel`	Button, ButtonRef, Image, ImageRef, Text, TextRef, TouchableWithoutFeedback, View, and ViewRef	A screen reader reads this string when a user selects the associated element. See also How accessibilityLabel works below.	accessibilityLabel
`accessibilityRole`	TouchableWithoutFeedback, View, and ViewRef	Communicates the purpose of a component to the user of an assistive technology. You.i React Native supports every role listed for accessibilityRole.	accessibilityRole
`accessibilityStates`¹	TouchableWithoutFeedback, View, and ViewRef	Describes the current state of a component to the user of an assistive technology. You.i React Native supports every state listed for accessibilityStates.	accessibilityStates
`onAccessibilityAction`	View, and ViewRef	The following standard actions are supported: - `activate` - `escape` - `magicTap` - `increment` - `decrement` Custom actions are not supported.	onAccessibilityAction
`onAccessibilityEscape`	View, and ViewRef		onAccessibilityEscape
`onAccessibilityTap`	View, and ViewRef		onAccessibilityTap
`onMagicTap`	View, and ViewRef		onMagicTap

We found that the prop accessibilityState mentioned in the Facebook RN documentation should be accessibilityStates.

Accessibility prop example

The following is an example of how to add accessibility props to your application. To see this example in context, see our Quick Start Guide.

<View style={styles.buttonContainer}
  focusable={true}
  accessible={true}
  accessibilityLabel="My button"
  accessibilityHint="Button in your first app"
  accessibilityRole="button"
>

  <Button
    onPress={this.onMyButtonPress}
    title="My button"
  />
</View>

How accessibilityLabel works

A screen reader reads the accessibilityLabel string when a user selects the associated element.

If an accessibilityLabel is set for an accessible component, the label value is read. Note that if you pass a string whose contents are whitespace to the accessibilityLabel, the screen reader reads out the whitespace.
If an accessibilityLabel isn’t set for an accessible component, the contents of the component are read.
If an accessibilityLabel is set to an empty string for an accessible component, the contents of the component are read. Facebook RN, by contrast, reads nothing in this situation.

Support for the AccessibilityInfo module

You.i React Native supports the Facebook RN AccessibilityInfo module, which allows you to confirm whether the screen reader functionality on the device is currently active. To know more about the methods supported by You.i React Native for each target platform, see AccessibilityInfo.

Enabling accessibility in After Effects

Screen reader functionality is supported for screen elements like buttons, scrolling lists, and static images created within an After Effects layout. Be aware that some elements like buttons and text inputs have default accessibility behaviors, while others don’t. If you don’t specify accessibility attributes as described in this section, you may see the default behaviors in some screen elements in your apps, and none in others.

You can specify attributes for this functionality in After Effects by adding accessibility properties to your layer comments for each element before you export. All you have to do is type in the property for the associated attribute in the layer comment field.

For example, the following image shows a Back button with accessibility attributes set within layer comments in the After Effects timeline view.

Accessibility attributes: label, states, role, hint

These accessibility comments are React Native props that are picked up from After Effects when generating an RN or a C++ app:

accessibilityLabel
accessibilityHint
accessibilityStates
accessibilityRole

When a screen element is activated via a gesture from a user, screen reader capability in the device reads the attributes aloud in this order: label, states, role, hint.

Depending on the component you’re creating in After Effects, you’ll need to input a particular, preset accessibilityRole, such as button for a button. The same applies to accessibilityStates. You.i Platform supports all of the roles available in React Native; accessibilityStates supported include disabled, checked, and expanded.

For the full list of accessibility roles, see Facebook’s RN documentation on accessibilityRole.

For hints and labels, consider the needs of the user and the design of the final app. Typically, the accessibilityHint tells a user the action performed by the element they’re activating. For example, a back button hint might be “navigates to the previous screen.” The accessibilityLabel performs a similar function, except that the label for a back button might be “go back.”

If a user requests the whole screen to be read one element at a time, both the accessibilityLabel and the accessibilityHint are read. However, if the entire screen is being read, attributes are read in this order: label, states, role (hint is not read). This might affect your decisions about what you want the label and the hint to be.

The tags associated with each designation, such as accessibilityLabel: “Back”, allow the screen reader feature to read that tag for each screen element in a view.

For more on how these props work, see Facebook’s Accessibility documentation. And for more examples like the one above, refer to RNSampleApp in the You.i Platform package files.

C++ accessibility attributes: CYIAccessibilityAttributes

Layer comments in After Effects work similarly for both C++ apps and React Native apps. For a C++ application, CYIAccessibilityAttributes is the class you’d interface with directly to enable screen reading functionality, whereas the React Native framework interfaces with that class for you when developing a React Native application. See our API documentation on CYIAccessibilityAttributes for more information.

Limitations

Generally, any screen element that you create in After Effects that has accessibility information listed in the layer comments for that element is read. One exception involves scrolling lists: when creating a scrolling list, the list must use a row or column arrangement if you want the list item’s index to be read.

While React Native allows you to create variable strings that refer to other props, in After Effects the layer comments are static strings that can’t reference other props. To handle this limitation, rather than inserting your comments in AE, use the Ref component associated with the screen element in AE, and set any applicable RN accessibility props within that Ref component.

Best practices for developing accessible apps

Follow these best practices for developing accessible apps using You.i React Native:

General best practices

Accessibility attributes set for a component in RN app code will override accessibility attributes set for that component in AE.
Annotate your app code with appropriate labels or hints using accessibilityHint and accessibilityLabel to control the announcement of special characters. For example, in our Quick Start Guide we annotate You.i TV as You I TV.
```
 <Text
   style={[styles.bodyText, themeStyles.bodyText]}
   accessibilityLabel="https://developer dot you i dot tv"
   >
   https://developer.youi.tv
 </Text>
```
Provide as much information to the user as you can. For example, use accessibilityRole to announce the purpose of a component and accessibilityStates to announce a component’s current state.
Use the AccessibilityInfo module that provides methods, such as setAccessibilityFocus and announceForAccessibility, to customize the accessibility features in your app.
You.i React Native apps don’t automatically read text embedded in images. Instead, create a text element in a View component and add an accessibilityLabel with any text in the image that you want announced.
Use a flag that can be tracked by the app so that hints or labels are read only at app launch.
If the screen reader is enabled at app launch, conditionally render a modal overlay to add a welcome message on app launch that includes specific hints.

Focus best practices

If the screen reader is turned on after an app is launched, You.i Platform automatically moves the accessibility focus to the currently focused item if it’s accessible. If there’s currently no focus, or if the focused item isn’t accessible, You.i Platform searches for an accessible focus item from the top-left corner, in left-to-right reading order. As a result, it’s a good idea for your app to handle the state change when the screen reader is enabled by explicitly setting the accessibility focus to a specific location.

You can use addEventListener and setAccessibilityFocus to listen for the screen reader state change and set the accessibility focus; see AccessibilityInfo in the Facebook RN docs.

Important

Focus behavior differs by platform; consult the accessibility topic for your target platform. You can see the list of topics in the left-hand navigation menu.

Focus on 10ft devices

Navigation focus allows users to navigate between different elements or screens in an app. Accessibility focus follows the element that already has navigation focus.
If an element doesn’t have navigation focus, a user can’t navigate to it or interact with it, but the element will still be announced when the screen reader reads the entire screen. As a result, to ensure that text is read aloud, make sure it’s part of a focusable view. For example, if a user is focused on an item in the settings page, there may be some information that is not selectable and cannot be navigated to. However, the screen reader will still read the information presented outside of the focus area.
You.i Platform provides additional help for elements without navigation focus. If navigation focus moves into a subtree where there are other accessible elements to be read, the screen reader reads those elements when the focus first enters. For example, if you navigate between the lander lists in our RNSampleApp, the header “Popular Movies” is read when you first move focus down to another list, but not as you move focus within that same list. The text is read the first time the button gets focus, but not again until focus leaves and re-enters that view. This behavior, which differs from standard 10ft behavior, ensures that items are visible to the screen reader even if they’re not focusable.

Use accessibilityHint on the relevant view for a screen reader to provide navigation hints.
Use accessibilityHint to configure hints based on the platform the app is running on.

Search best practices

Use accessibilityHint, accessibilityLabel, and accessibilityRole to configure the screen reader for search results or search text.

General limitations and known issues

The following are the current limitations and known issues for using accessibility with You.i React Native:

Facebook React Native doesn’t support announcing the row or column details for the currently focused element, so You.i React Native doesn’t support this for RN lists. But you can add app-side logic to announce this information to users.
If you’re using the speech synthesizer module to speak text and the screen reader is enabled on your device, you may hear an overlap of voices.
Appium tests don’t currently work when the screen reader is enabled. Accessibility support with Appium is being evaluated for inclusion.