From 284fdd8578c8df9ee68d861696e01806876d5242 Mon Sep 17 00:00:00 2001
From: wanxiankai <xiankai.wan@gmail.com>
Date: Sun, 12 Jul 2026 09:29:02 +0800
Subject: [PATCH] docs: clarify accessible name precedence

---
 docs/api/queries.md                    | 22 +++++++++++++++++++++-
 website/docs/14.x/docs/api/queries.mdx | 22 +++++++++++++++++++++-
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/docs/api/queries.md b/docs/api/queries.md
index 000732e73..620256407 100644
--- a/docs/api/queries.md
+++ b/docs/api/queries.md
@@ -188,7 +188,27 @@ const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });
 
 #### Options
 
-- `name`: Finds an element with given `role`/`accessibilityRole` and an accessible name (= accessability label or text content).
+- `name`: Finds an element with the given `role`/`accessibilityRole` and
+  [accessible name](https://reactnative.dev/docs/accessibility#accessibilitylabel). The name is
+  computed in the same priority order used by React Native accessibility:
+  1. `aria-labelledby` or `accessibilityLabelledBy`
+  2. `aria-label` or `accessibilityLabel`
+  3. `alt` for `Image`, a root `TextInput`'s `placeholder`, or the element's text content
+
+  Sources earlier in the list take precedence. For example, when a button has both an
+  `accessibilityLabel` and child text, query it by the label because the child text is not part of
+  its accessible name:
+
+  ```tsx
+  await render(
+    <Pressable accessibilityRole="button" accessibilityLabel="Submit form">
+      <Text>Submit</Text>
+    </Pressable>,
+  );
+
+  screen.getByRole('button', { name: 'Submit form' }); // matches
+  screen.queryByRole('button', { name: 'Submit' }); // returns null
+  ```
 
 - `disabled`: You can filter elements by their disabled state (coming either from `aria-disabled` prop or `accessbilityState.disabled` prop). The possible values are `true` or `false`. Querying `disabled: false` will also match elements with `disabled: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details).
   - See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `disabled` state.
diff --git a/website/docs/14.x/docs/api/queries.mdx b/website/docs/14.x/docs/api/queries.mdx
index ccf5075df..ba0f7add6 100644
--- a/website/docs/14.x/docs/api/queries.mdx
+++ b/website/docs/14.x/docs/api/queries.mdx
@@ -192,7 +192,27 @@ const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });
 
 #### Options {#by-role-options}
 
-- `name`: Finds an element with given `role`/`accessibilityRole` and an accessible name (= accessability label or text content).
+- `name`: Finds an element with the given `role`/`accessibilityRole` and
+  [accessible name](https://reactnative.dev/docs/accessibility#accessibilitylabel). The name is
+  computed in the same priority order used by React Native accessibility:
+  1. `aria-labelledby` or `accessibilityLabelledBy`
+  2. `aria-label` or `accessibilityLabel`
+  3. `alt` for `Image`, a root `TextInput`'s `placeholder`, or the element's text content
+
+  Sources earlier in the list take precedence. For example, when a button has both an
+  `accessibilityLabel` and child text, query it by the label because the child text is not part of
+  its accessible name:
+
+  ```tsx
+  await render(
+    <Pressable accessibilityRole="button" accessibilityLabel="Submit form">
+      <Text>Submit</Text>
+    </Pressable>,
+  );
+
+  screen.getByRole('button', { name: 'Submit form' }); // matches
+  screen.queryByRole('button', { name: 'Submit' }); // returns null
+  ```
 
 - `disabled`: You can filter elements by their disabled state (coming either from `aria-disabled` prop or `accessbilityState.disabled` prop). The possible values are `true` or `false`. Querying `disabled: false` will also match elements with `disabled: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details).
   - See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `disabled` state.