Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 71 ยท Components and Interaction

Accessibility in React Native

Make React Native apps usable with VoiceOver and TalkBack: accessibilityLabel, role, state, focus order, dynamic type, touch targets and color contrast.

Millions of people use phones with a screen reader, large text, reduced motion or a switch device. On iOS the screen reader is VoiceOver; on Android it is TalkBack. Both read your app aloud by walking through a tree of accessible elements and announcing each one's name, role and state. If your app is just a pile of unlabeled icons, that walk sounds like "button, button, button".

React Native gives you props that feed this tree. Using them is cheap, usually a few extra words per component, and it improves your app for everyone: bigger touch targets, readable contrast and clear states help people in sunlight, in a hurry, or with one hand busy. This lesson covers the props, the structure screen readers follow, text scaling, contrast, and a stand-in that prints an accessibility tree so you can see what a screen reader would announce.

Read-only and stand-in. VoiceOver and TalkBack only exist on devices, so the real props are shown in plain code blocks. The TryIts print an approximate accessibility tree and compute contrast ratios in plain JavaScript. To really test, turn on VoiceOver or TalkBack on a phone and use your app with the screen off.

What a screen reader announces

For each focused element a screen reader says, roughly: name, role, state, hint. For example: "Notifications, switch, on. Double tap to toggle." You supply those parts with props:

Prop Meaning
accessible Groups the element as one focusable unit (true) or leaves it out (false)
accessibilityLabel (or aria-label) The name read aloud
accessibilityRole (or role) What kind of thing it is: button, link, header, switch, image...
accessibilityState { disabled, selected, checked, busy, expanded }
accessibilityValue Current value of sliders or progress ({ min, max, now, text })
accessibilityHint An extra sentence about what happens, only when the label is not enough
alt (on Image) The description of an image

React Native also accepts web-style aria-* props such as aria-label, aria-checked, aria-disabled, aria-hidden and role. They are equivalent to the older accessibility* names, and many teams now prefer them because the vocabulary matches the web.

Labels and roles

Text is already read aloud, and Pressable is accessible by default, so a button that contains text often needs nothing extra. The trouble starts with icon-only controls and with elements that hide their purpose.

TSX
import { Pressable, Text, Image } from 'react-native';

// Icon-only button: without a label this is announced as just "button"
<Pressable
  accessibilityRole="button"
  accessibilityLabel="Delete message"
  onPress={deleteMessage}
>
  <TrashIcon />
</Pressable>

// A heading helps people jump between sections
<Text accessibilityRole="header" style={{ fontSize: 22, fontWeight: '700' }}>
  Settings
</Text>

// A decorative image should be skipped, a meaningful one described
<Image source={require('./divider.png')} aria-hidden />
<Image source={logo} alt="Acme Coffee logo" />

Write labels that describe the purpose, not the look: "Delete message", not "Red trash can". Do not put the role in the label ("Delete button"), because the role is announced separately. A hint is for results that are not obvious ("Opens the receipt"), and it should be short.

State: tell users what is on

Visual state (a filled checkbox, a selected tab, a greyed-out button) is invisible to a screen reader unless you pass it through:

TSX
<Pressable
  accessibilityRole="switch"
  accessibilityLabel="Notifications"
  accessibilityState={{ checked: enabled }}
  onPress={() => setEnabled(!enabled)}
>
  {/* custom switch drawing */}
</Pressable>

<Pressable
  accessibilityRole="button"
  accessibilityState={{ disabled: saving, busy: saving }}
  disabled={saving}
>
  <Text>Save</Text>
</Pressable>

With the state set, the same control is announced as "Notifications, switch, on", and it changes when the user toggles it. Without it, the screen reader says "Notifications, button" forever, which is wrong and confusing.

Grouping and hiding

By default every Text is a separate stop. A card with a title, a price and a button would take three swipes, and the price alone ("$12") means nothing. Setting accessible on the parent merges the children into one element, and you can give the group a single sentence:

TSX
<View
  accessible
  accessibilityLabel="Espresso, 3 dollars 50, in stock"
  accessibilityRole="button"
>
  <Text>Espresso</Text>
  <Text>$3.50</Text>
  <Text>In stock</Text>
</View>

To hide something purely decorative, use aria-hidden (iOS: accessibilityElementsHidden, Android: importantForAccessibility="no-hide-descendants"). Hide only things that carry no information, never a control the user needs.

Focus order and announcements

Screen readers move through elements in layout order, left to right and top to bottom, which usually equals the order in your JSX. Keep your JSX order the same as the visual order and you rarely need to do anything. Avoid tricks that put a visually-first element last in the code.

Two more tools exist for dynamic changes:

  • AccessibilityInfo.announceForAccessibility('Message sent') speaks a short message, for example after a background save.
  • AccessibilityInfo.isScreenReaderEnabled() and AccessibilityInfo.isReduceMotionEnabled() tell you the user's settings, so you can skip an animation or add a text description.

On Android, accessibilityLiveRegion="polite" makes changes inside a view announce themselves. A modal screen should trap the reader inside it: iOS has accessibilityViewIsModal for this, and React Native's Modal component already behaves correctly.

What VoiceOver and TalkBack say

Name From label, alt or text.
Role Button, link, header, switch.
State On, selected, disabled, busy.
Hint Optional, short.
1 / 2

Dynamic type, contrast and touch targets

Text size. Users can raise the system font size. React Native scales Text by default (allowFontScaling is true). Do not turn it off to protect a design. If a header becomes too large, cap it with maxFontSizeMultiplier={1.5} and design layouts that tolerate wrapping: avoid fixed heights on containers that hold text, and prefer minHeight with padding.

Contrast. WCAG 2 asks for a contrast ratio of at least 4.5 to 1 for normal text and 3 to 1 for large text (roughly 18 points, or 14 points bold) and for icons that carry meaning. Light grey placeholder text on white is the classic failure.

Touch targets. A tap target should be about 44 by 44 points on iOS and 48 by 48 density-independent pixels on Android. A small icon can stay small if you grow its tappable area with padding or hitSlop (see Pressable, Buttons and Touch Feedback).

Stand-in: an accessibility tree printer

The function below walks a small element tree and prints what a screen reader would roughly announce. It applies the real rules in simplified form: Text and Pressable are accessible by default, an element with aria-hidden is skipped, a label wins over inner text, and state is read after the role. It also warns when something focusable has no name.

Print what a screen reader would announce

Swipe order equals list order. The decorative image never appears, the switch announces its state, the button gets its name from the inner Text, and the icon-only button is flagged. Real screen readers have more rules, but the lesson holds: the tree you build in JSX is the tree people hear.

Stand-in: a contrast checker

Contrast is just arithmetic, which makes it easy to test in code. The formula converts each color to a relative luminance and divides the lighter by the darker (each plus 0.05).

Check WCAG contrast ratios

Notice that the popular grey #777777 on white misses the 4.5 target by a hair, and darkening it only slightly (#595959) fixes it. A sky-blue button with white text also falls short, so a darker blue is needed there.

Test with the real tools

  1. Turn on VoiceOver (iOS Settings, Accessibility) or TalkBack (Android Settings, Accessibility) and navigate your screens with swipes.
  2. Raise the system font size to the largest setting and look for clipped text.
  3. Use the platform scanners: Xcode's Accessibility Inspector and Android's Accessibility Scanner.
  4. In automated tests, query by role and label (see Testing React Native Apps); if a test cannot find your button by name, neither can a screen reader. The web lessons on accessibility in React share many of the same ideas.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. An icon-only trash button has no accessibilityLabel. What does a screen reader most likely announce?

    Pressable is focusable, but without text or a label there is no name to read, so users only hear the role.
  2. 2. Which label is best for a button that removes a message?

    A label should name the purpose. Do not describe the look, and do not repeat the role, which is announced separately.
  3. 3. How do you make a custom switch announce whether it is on?

    Visual state is invisible to screen readers. Pass checked, selected, disabled or busy through accessibilityState.
  4. 4. What is the minimum contrast ratio WCAG AA asks for normal-size text?

    4.5 to 1 for normal text; large text and meaningful icons need 3 to 1.
  5. 5. Why should you avoid allowFontScaling={false} on body text?

    Dynamic type is an accessibility setting. Cap extreme sizes with maxFontSizeMultiplier and design layouts that can wrap.

Summary

  • Screen readers announce name, role, state and optionally a hint; you provide them with accessibilityLabel, accessibilityRole, accessibilityState and alt (or the aria-* equivalents).
  • Icon-only controls always need a label that describes the purpose; decorative items get aria-hidden.
  • Pass visual state (checked, selected, disabled, busy) through accessibilityState.
  • Group related text with accessible on the parent so a card reads as one sentence.
  • Keep JSX order equal to visual order, let text scale, aim for 4.5 : 1 contrast and 44 to 48 point touch targets.
  • Test with VoiceOver and TalkBack, not only by reading code.

Next, show a lot of data efficiently in FlatList Essentials.