fix(a11y): android prevent redundant double screen reader focus step on <Text role="link"> (#54515)

Summary:
Resolves https://github.com/facebook/react-native/issues/53240

Resolves an Android-only issue where a top-level `<Text role="link">Link Text</Text>` would generate two accessibility (screen reader) focus steps:
1. "Link Text. Link. Links available, use tap with 3 fingers to view."
2. "Link Text. Link. Double-tap to activate."

This behavior was inconsistent with iOS behavior, which generated a single screen reader step, resulting in a poor user experience due to unnecessary repetition of information.

This PR resolves the issue in a way that allows mixing plain text and links while still yielding additional focus steps for nested links if there is any other text present or if there are multiple links.

## Android after

https://github.com/user-attachments/assets/646b64af-a7eb-4b28-8735-546b9909a510

## Android before

https://github.com/user-attachments/assets/43bd9ee9-890f-43ca-9363-ade8b45dea27

## iOS (for comparison)

https://github.com/user-attachments/assets/807d1771-e3e7-4dca-9409-7697d1a0cb9c

## Changelog:

<!-- Help reviewers and the release process by writing your own changelog entry.

[ANDROID] [FIXED] a11y: prevent redundant double screen reader focus steps on `<Text role="link">`
Pick one each for the category and type tags:

[ANDROID|GENERAL|IOS|INTERNAL] [BREAKING|ADDED|CHANGED|DEPRECATED|REMOVED|FIXED|SECURITY] - Message

For more details, see:
https://reactnative.dev/contributing/changelogs-in-pull-requests

Pull Request resolved: https://github.com/facebook/react-native/pull/54515

Test Plan: Open RN Tester on "Text with link role" example and test with screen reader.

Reviewed By: cipolleschi

Differential Revision: D87464727

Pulled By: joevilches

fbshipit-source-id: a69df5b63128886ea5c45b22e068d455ee808c0f
This commit is contained in:
Maciej Jastrzębski authored and meta-codesync[bot] committed 2025-11-26 11:47:13 -08:00
1 parent f60789abac
commit 06786a8afa
2 files changed
+80 -16

No files matched your search

@@ -290,22 +290,26 @@ internal class ReactTextViewAccessibilityDelegate(
init {
val accessibleLinks = mutableListOf<AccessibleLink>()
val spans = text.getSpans(0, text.length, ClickableSpan::class.java)
spans.sortBy { text.getSpanStart(it) }
for (i in spans.indices) {
val span = spans[i]
val start = text.getSpanStart(span)
val end = text.getSpanEnd(span)
// zero length spans, and out of range spans should not be included.
if (start == end || start < 0 || end < 0 || start > text.length || end > text.length) {
continue
}
val link = AccessibleLink()
link.description = text.subSequence(start, end).toString()
link.start = start
link.end = end
link.id = i
accessibleLinks.add(link)
// Do not generate virtual views if whole text is a single link
if (!isWholeTextSingleLink(text, spans)) {
spans.sortBy { text.getSpanStart(it) }
for (i in spans.indices) {
val span = spans[i]
val start = text.getSpanStart(span)
val end = text.getSpanEnd(span)
// zero length spans, and out of range spans should not be included.
if (start == end || start < 0 || end < 0 || start > text.length || end > text.length) {
continue
}
val link = AccessibleLink()
link.description = text.subSequence(start, end).toString()
link.start = start
link.end = end
link.id = i
accessibleLinks.add(link)
}
}
links = accessibleLinks
}
@@ -342,3 +346,14 @@ internal class ReactTextViewAccessibilityDelegate(
}
}
}
private fun isWholeTextSingleLink(text: Spanned, spans: Array<ClickableSpan>): Boolean {
if (spans.size != 1) {
return false
}
val span = spans[0]
val start = text.getSpanStart(span)
val end = text.getSpanEnd(span)
return start == 0 && end == text.length
}
@@ -14,7 +14,7 @@ import type {TextLayoutLine} from 'react-native/Libraries/Types/CoreEventTypes';
import RNTesterText from '../../components/RNTesterText';
import {useTheme} from '../../components/RNTesterTheme';
import {useState} from 'react';
import {View} from 'react-native';
import {StyleSheet, Text, View} from 'react-native';
function InlineView(props: {
textAlign: 'auto' | 'left' | 'right' | 'center' | 'justify',
@@ -193,6 +193,49 @@ component RtlAndInlineViewsExample() {
);
}
component TextWithLinkRoleExample() {
const handlePress = () => console.log('Link Press');
return (
<View>
<Text role="link" style={styles.link} onPress={handlePress}>
Link Text
</Text>
<Text>
<Text role="link" style={styles.link} onPress={handlePress}>
Nested Link
</Text>
</Text>
<Text>
Before{' '}
<Text role="link" style={styles.link} onPress={handlePress}>
Nested Link
</Text>
{' After'}
</Text>
<Text>
<Text role="link" style={styles.link} onPress={handlePress}>
Nested Link 1
</Text>
{' - '}
<Text role="link" style={styles.link} onPress={handlePress}>
Nested Link 2
</Text>
</Text>
</View>
);
}
const styles = StyleSheet.create({
link: {
color: 'teal',
textDecorationLine: 'underline',
},
});
export default [
{
title: 'Empty Text',
@@ -222,4 +265,10 @@ export default [
scrollable: true,
render: NumberOfLinesTextLayoutExample,
},
{
title: 'Text with link role',
name: 'textWithLinkRole',
description: 'Shows the a11y behavior of Text with role="link"',
render: TextWithLinkRoleExample,
},
] as $ReadOnlyArray<RNTesterModuleExample>;