diff --git a/docs/6.x/docs/guides/migration.md b/docs/6.x/docs/guides/migration.md
index 30cbc45a6a..a7e750b626 100644
--- a/docs/6.x/docs/guides/migration.md
+++ b/docs/6.x/docs/guides/migration.md
@@ -309,7 +309,7 @@ As with `roundness`, Paper ignores these keys, and TypeScript only reports them
Components now use React Native's `aria-*` props and `role` instead of the `accessibility*` props. `accessibilityLabel` is now `aria-label`, the `accessibilityRole` of `Button` is now `role`, and the `accessibilityState` of `FAB` and `Menu.Item` is now `aria-checked` and `aria-selected`.
-`Checkbox.Item`, `RadioButton.Item`, `FAB`, `Menu.Item`, `List.Accordion` and `Switch` no longer accept `accessibilityLabel`, so TypeScript reports an error. Components whose props extend React Native's view props, such as `Button`, `Chip` and `DataTable.Pagination`, still compile with the old props, but pass them to their outer container instead of the element they used to label.
+`Checkbox.Item`, `RadioButton.Item`, `FAB`, `Menu.Item`, `List.Accordion` and `Switch` no longer accept `accessibilityLabel`, so TypeScript reports an error. Components whose props extend React Native's view props, such as `Chip` and `DataTable.Pagination`, still compile with the old props, but pass them to their outer container instead of the element they used to label.
Props that label a part of a component keep their names, e.g. `closeIconAccessibilityLabel` on `Chip` and `dismissAccessibilityLabel` on `Modal`.
diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 93f5a59e59..6de64ccf5f 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -260,8 +260,14 @@ const Button = ({
children,
'aria-label': ariaLabel,
'aria-expanded': ariaExpanded,
+ 'aria-busy': ariaBusy,
+ 'aria-checked': ariaChecked,
+ 'aria-selected': ariaSelected,
+ accessibilityLabel,
+ accessibilityState,
+ accessibilityRole,
accessibilityHint,
- role = 'button',
+ role,
hitSlop,
onPress,
onPressIn,
@@ -316,11 +322,43 @@ const Button = ({
// toggle colors, no shape flip, and no toggle state. Every other use of
// the toggle state goes through this value.
const toggleSelected = isMode('text') ? undefined : selected;
- // React Native's types have no `aria-pressed`.
+
+ // As on React Native itself, an `aria-*` prop wins over the same
+ // `accessibilityState` field. Both are passed on as `aria-*` props, since
+ // react-native-web does not support `accessibilityState`.
+ const busy = loading || (ariaBusy ?? accessibilityState?.busy);
+ const checked = ariaChecked ?? accessibilityState?.checked;
+
+ // Android only: React Native puts a busy view's state into its content
+ // description ("Save draft, busy"), and TalkBack reads that instead of the
+ // text inside the button. Without a label, the description would be just
+ // "busy", so the button's text becomes its label. When the content is not
+ // only text (strings and numbers, e.g. `Uploading {count} files`), it
+ // cannot be read here: the busy state is left out instead, so TalkBack
+ // still reads the content.
+ const needsAndroidBusyLabel =
+ Platform.OS === 'android' &&
+ busy === true &&
+ ariaLabel === undefined &&
+ accessibilityLabel === undefined;
+ const childrenParts = React.Children.toArray(children);
+ const childrenText =
+ childrenParts.length > 0 &&
+ childrenParts.every(
+ (part) => typeof part === 'string' || typeof part === 'number'
+ )
+ ? childrenParts.join('')
+ : undefined;
+ const pressableLabel = needsAndroidBusyLabel ? childrenText : ariaLabel;
+ const pressableBusy =
+ needsAndroidBusyLabel && childrenText === undefined ? undefined : busy;
+
+ // React Native's types have no `aria-pressed`. A given `checked` state
+ // still applies where the toggle state is not exposed as checked.
const toggleStateProps =
Platform.OS === 'web'
- ? { 'aria-pressed': toggleSelected }
- : { 'aria-checked': toggleSelected };
+ ? { 'aria-pressed': toggleSelected, 'aria-checked': checked }
+ : { 'aria-checked': toggleSelected ?? checked };
// When the button is `selected`, flip the requested shape so the
// unselected/selected pair contrasts visually (round ↔ square).
@@ -528,10 +566,19 @@ const Button = ({
onPressIn={hasPassedTouchHandler ? handlePressIn : undefined}
onPressOut={hasPassedTouchHandler ? handlePressOut : undefined}
delayLongPress={delayLongPress}
- aria-label={ariaLabel}
- aria-expanded={ariaExpanded}
+ accessibilityLabel={accessibilityLabel}
+ accessibilityRole={accessibilityRole}
+ aria-label={pressableLabel}
+ aria-expanded={ariaExpanded ?? accessibilityState?.expanded}
+ aria-busy={pressableBusy}
+ aria-selected={ariaSelected ?? accessibilityState?.selected}
accessibilityHint={accessibilityHint}
- role={role}
+ // `role` wins over `accessibilityRole`, so the default role steps
+ // aside for a given `accessibilityRole`. The two use different
+ // names (`header` / `heading`), so one is never passed as the other.
+ role={
+ role ?? (accessibilityRole === undefined ? 'button' : undefined)
+ }
aria-disabled={disabled}
{...toggleStateProps}
accessible={accessible}
@@ -556,7 +603,13 @@ const Button = ({
) : null}
{loading ? (
-
+ // The button itself is busy (`aria-busy`), so the indicator is
+ // not a separate progress element for assistive technology.
+
) : null}
{
expect(screen.getByRole('button')).toHaveProp('accessibilityHint', 'hint');
});
+describe('accessibility props', () => {
+ it('exposes accessibilityLabel, accessibilityState and loading on the button only', async () => {
+ await render(
+
+ );
+
+ expect(
+ screen.getByRole('button', {
+ name: 'Save draft',
+ expanded: false,
+ busy: true,
+ })
+ ).toBeOnTheScreen();
+ expect(screen.root).not.toHaveProp('accessibilityLabel');
+ expect(screen.root).not.toHaveProp('accessibilityState');
+ // The button itself is busy, so the indicator is hidden.
+ expect(screen.queryByRole('progressbar')).not.toBeOnTheScreen();
+ expect(
+ screen.getByRole('progressbar', { includeHiddenElements: true })
+ ).toBeOnTheScreen();
+ });
+
+ it('exposes aria-* states on the button, ahead of accessibilityState', async () => {
+ await render(
+
+ );
+
+ const button = screen.getByRole('button', {
+ name: 'Save',
+ expanded: true,
+ busy: false,
+ selected: true,
+ });
+ // `getByRole` filters `checked` for checkable roles only.
+ expect(button).toHaveProp(
+ 'accessibilityState',
+ expect.objectContaining({ checked: 'mixed' })
+ );
+ expect(screen.root).not.toHaveProp('accessibilityState');
+ });
+
+ // On Android, React Native puts "busy" into the content description, which
+ // TalkBack reads instead of the button's text, so a loading button without
+ // a label is labelled by its text there.
+ it('labels a loading button by its text on Android', async () => {
+ jest.replaceProperty(Platform, 'OS', 'android');
+
+ await render(
+
+ );
+
+ expect(screen.getByRole('button', { busy: true })).toHaveProp(
+ 'accessibilityLabel',
+ 'Uploading 3 files'
+ );
+ });
+
+ it('leaves the name of a loading button to content that is not only text on Android', async () => {
+ jest.replaceProperty(Platform, 'OS', 'android');
+
+ await render(
+
+ );
+
+ // The busy state is left out, so TalkBack reads the content.
+ expect(screen.getByRole('button', { busy: false })).not.toHaveProp(
+ 'accessibilityLabel'
+ );
+ });
+
+ it('uses a given accessibilityRole instead of the default button role', async () => {
+ await render(
+
+ );
+
+ expect(screen.getByRole('link', { name: 'Docs' })).toBeOnTheScreen();
+ expect(screen.queryByRole('button')).not.toBeOnTheScreen();
+ });
+});
+
it('should execute onPressIn', async () => {
const onPressInMock = jest.fn();
const onPress = jest.fn();
diff --git a/src/components/__tests__/__snapshots__/Button.test.tsx.snap b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
index e7695e1022..af79fa9430 100644
--- a/src/components/__tests__/__snapshots__/Button.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
@@ -785,6 +785,7 @@ exports[`renders loading button 1`] = `
>