From 6a74cfa0b00588200b7a9ce9da52a32360dc3603 Mon Sep 17 00:00:00 2001 From: Joe Vilches Date: Tue, 26 Aug 2025 19:45:19 -0400 Subject: [PATCH 1/3] documentation for experimental_accessibilityOrder --- docs/accessibilityorder.md | 108 +++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/accessibilityorder.md diff --git a/docs/accessibilityorder.md b/docs/accessibilityorder.md new file mode 100644 index 00000000000..666508b8d96 --- /dev/null +++ b/docs/accessibilityorder.md @@ -0,0 +1,108 @@ +--- +id: accessibilityorder +title: experimental_accessibilityOrder ⚗️ +--- + +:::important +**This API is experimental.** Experimental APIs may contain bugs and are likely to change in a future version of React Native. Don't use them in production. +::: + +`experimental_accessibilityOrder` is a prop on [`View`](view.md) which indicates the order in which an assistive technology focuses descendants of the `View`. This prop takes an array of strings where each string is a [`nativeID`](view.md#nativeid) of some descendant component whose order is being defined. This prop does not enable accessibility itself, each referenced component still needs to be accessible by setting [`accessible`](view.md#accessible) to true. This prop is both **nestable** and **exhaustive** meaning + +* If `experimental_accessibilityOrder` contains a reference to some non-accessible component, it will focus the descendants of that component in the default order. Additionally, it can also contain a reference to other components that also have an `experimental_accessibilityOrder`. +* If some component that is otherwise accessible is not directly referenced in `experimental_accessibilityOrder`, or nested within some container directly referenced in `experimental_accessibilityOrder`, then it will not be accessible. + +| Type | +| ------- | +| array of strings | + +## Guide + +:::note +For the sake of brevity, layout is excluded in the following examples even though it dictates the default focus order. Assume the document order matches the layout order. +::: + +`experimental_accessibilityOrder` lets you define the order in which assistive technologies focus descendant components. It is an array of [`nativeIDs`](view.md#nativeid) that are set on the components whose order you are controlling. For example: + +``` + + + + + +``` + +Assistive technologies will focus the `View` with `nativeID` of `“B”`, then `“C”`, then `“A”`. + +`experimental_accessibilityOrder` will not “turn on” accessibility for the components it references, that still needs to be done. So if we remove `accessible={true}` on `“C”` above like so + +``` + + + + + +``` + +then the new order will be `“B”` then `“A”`, even though `“C”` is still in `experimental_accessibilityOrder`. + +`experimental_accessibilityOrder` will “turn off” accessibility of components it doesn’t reference, however. + +``` + + + + + + +``` + +The order of the above example would be `“B”`, `“C”`, `“A”`. `“D”` will never get focused. In this sense `experimental_accessibilityOrder` is *exhaustive*. + +There are still valid reasons to include an non-accessible component in `experimental_accessibilityOrder`. Consider + +``` + + + + + + + + + +``` + +The focus order will be `“B”`, `“D”`, `“E”`, `“F”`, `“A”`. Even though `“D”`, `“E”`, and `“F”` are not directly referenced in `experimental_accessibilityOrder`, `“C”` is directly referenced. In this instance `“C”` in an *accessibility container* - it contains accessible elements, but is not accessible itself. If an accessibility container is referenced in `experimental_accessibilityOrder` then the default order of the elements it contains is applied. In this sense `experimental_accessibilityOrder` is *nestable*. + +`experimental_accessibilityOrder` can also reference another component with `experimental_accessibilityOrder` + +``` + + + + + + + + + +``` + +The focus order will be `“B”`, `“F”`, `“E”`, `“D”`, `“A”`. + +A component cannot be both an accessibility container and an accessibility element (`accessible={true}`). So if we have + +``` + + + + + + + + + +``` + +The focus order would be `“B”`, `“C”`, `“A”`. `“D”`, `“E”`, and `“F”` are no longer in a container, so the exhaustive nature of `experimental_accessibilityOrder` means they will be excluded. From 0d786c83182a8798e7e8bdd5091b4df888327bfe Mon Sep 17 00:00:00 2001 From: Joe Vilches Date: Wed, 27 Aug 2025 12:16:42 -0400 Subject: [PATCH 2/3] bake documentation into existing pages --- docs/accessibility.md | 95 ++++++++++++++++++++++++++++++++ docs/accessibilityorder.md | 108 ------------------------------------- docs/view.md | 19 +++++++ docs/virtualview.md | 2 +- 4 files changed, 115 insertions(+), 109 deletions(-) delete mode 100644 docs/accessibilityorder.md diff --git a/docs/accessibility.md b/docs/accessibility.md index 0b42f659a64..02a30004d38 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -337,6 +337,101 @@ Indicates whether a selectable element is currently selected or not. | ------- | | boolean | +### `experimental_accessibilityOrder` + +:::important Experimental ⚗️ +**This API is experimental.** Experimental APIs may contain bugs and are likely to change in a future version of React Native. Don't use them in production. +::: +:::note +For the sake of brevity, layout is excluded in the following examples even though it dictates the default focus order. Assume the document order matches the layout order. +::: + +`experimental_accessibilityOrder` lets you define the order in which assistive technologies focus descendant components. It is an array of [`nativeIDs`](view.md#nativeid) that are set on the components whose order you are controlling. For example: + +``` + + + + + +``` + +Assistive technologies will focus the `View` with `nativeID` of `B`, then `C`, then `A`. + +`experimental_accessibilityOrder` will not “turn on” accessibility for the components it references, that still needs to be done. So if we remove `accessible={true}` on `C` above like so + +``` + + + + + +``` + +then the new order will be `B` then `A`, even though `C` is still in `experimental_accessibilityOrder`. + +`experimental_accessibilityOrder` will “turn off” accessibility of components it doesn’t reference, however. + +``` + + + + + + +``` + +The order of the above example would be `B`, `C`, `A`. `D` will never get focused. In this sense `experimental_accessibilityOrder` is *exhaustive*. + +There are still valid reasons to include an non-accessible component in `experimental_accessibilityOrder`. Consider + +``` + + + + + + + + + +``` + +The focus order will be `B`, `D`, `E`, `F`, `A`. Even though `D`, `E`, and `F` are not directly referenced in `experimental_accessibilityOrder`, `C` is directly referenced. In this instance `C` in an *accessibility container* - it contains accessible elements, but is not accessible itself. If an accessibility container is referenced in `experimental_accessibilityOrder` then the default order of the elements it contains is applied. In this sense `experimental_accessibilityOrder` is *nestable*. + +`experimental_accessibilityOrder` can also reference another component with `experimental_accessibilityOrder` + +``` + + + + + + + + + +``` + +The focus order will be `B`, `F`, `E`, `D`, `A`. + +A component cannot be both an accessibility container and an accessibility element (`accessible={true}`). So if we have + +``` + + + + + + + + + +``` + +The focus order would be `B`, `C`, `A`. `D`, `E`, and `F` are no longer in a container, so the exhaustive nature of `experimental_accessibilityOrder` means they will be excluded. + + ### `importantForAccessibility`
Android
In the case of two overlapping UI components with the same parent, default accessibility focus can have unpredictable behavior. The `importantForAccessibility` property will resolve this by controlling if a view fires accessibility events and if it is reported to accessibility services. It can be set to `auto`, `yes`, `no` and `no-hide-descendants` (the last value will force accessibility services to ignore the component and all of its children). diff --git a/docs/accessibilityorder.md b/docs/accessibilityorder.md deleted file mode 100644 index 666508b8d96..00000000000 --- a/docs/accessibilityorder.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: accessibilityorder -title: experimental_accessibilityOrder ⚗️ ---- - -:::important -**This API is experimental.** Experimental APIs may contain bugs and are likely to change in a future version of React Native. Don't use them in production. -::: - -`experimental_accessibilityOrder` is a prop on [`View`](view.md) which indicates the order in which an assistive technology focuses descendants of the `View`. This prop takes an array of strings where each string is a [`nativeID`](view.md#nativeid) of some descendant component whose order is being defined. This prop does not enable accessibility itself, each referenced component still needs to be accessible by setting [`accessible`](view.md#accessible) to true. This prop is both **nestable** and **exhaustive** meaning - -* If `experimental_accessibilityOrder` contains a reference to some non-accessible component, it will focus the descendants of that component in the default order. Additionally, it can also contain a reference to other components that also have an `experimental_accessibilityOrder`. -* If some component that is otherwise accessible is not directly referenced in `experimental_accessibilityOrder`, or nested within some container directly referenced in `experimental_accessibilityOrder`, then it will not be accessible. - -| Type | -| ------- | -| array of strings | - -## Guide - -:::note -For the sake of brevity, layout is excluded in the following examples even though it dictates the default focus order. Assume the document order matches the layout order. -::: - -`experimental_accessibilityOrder` lets you define the order in which assistive technologies focus descendant components. It is an array of [`nativeIDs`](view.md#nativeid) that are set on the components whose order you are controlling. For example: - -``` - - - - - -``` - -Assistive technologies will focus the `View` with `nativeID` of `“B”`, then `“C”`, then `“A”`. - -`experimental_accessibilityOrder` will not “turn on” accessibility for the components it references, that still needs to be done. So if we remove `accessible={true}` on `“C”` above like so - -``` - - - - - -``` - -then the new order will be `“B”` then `“A”`, even though `“C”` is still in `experimental_accessibilityOrder`. - -`experimental_accessibilityOrder` will “turn off” accessibility of components it doesn’t reference, however. - -``` - - - - - - -``` - -The order of the above example would be `“B”`, `“C”`, `“A”`. `“D”` will never get focused. In this sense `experimental_accessibilityOrder` is *exhaustive*. - -There are still valid reasons to include an non-accessible component in `experimental_accessibilityOrder`. Consider - -``` - - - - - - - - - -``` - -The focus order will be `“B”`, `“D”`, `“E”`, `“F”`, `“A”`. Even though `“D”`, `“E”`, and `“F”` are not directly referenced in `experimental_accessibilityOrder`, `“C”` is directly referenced. In this instance `“C”` in an *accessibility container* - it contains accessible elements, but is not accessible itself. If an accessibility container is referenced in `experimental_accessibilityOrder` then the default order of the elements it contains is applied. In this sense `experimental_accessibilityOrder` is *nestable*. - -`experimental_accessibilityOrder` can also reference another component with `experimental_accessibilityOrder` - -``` - - - - - - - - - -``` - -The focus order will be `“B”`, `“F”`, `“E”`, `“D”`, `“A”`. - -A component cannot be both an accessibility container and an accessibility element (`accessible={true}`). So if we have - -``` - - - - - - - - - -``` - -The focus order would be `“B”`, `“C”`, `“A”`. `“D”`, `“E”`, and `“F”` are no longer in a container, so the exhaustive nature of `experimental_accessibilityOrder` means they will be excluded. diff --git a/docs/view.md b/docs/view.md index f26406d2412..e4a0ce78a9a 100644 --- a/docs/view.md +++ b/docs/view.md @@ -383,6 +383,25 @@ Setting to false prevents direct children of the view from being removed from th --- +### `experimental_accessibilityOrder` + +:::important Experimental ⚗️ +**This API is experimental.** Experimental APIs may contain bugs and are likely to change in a future version of React Native. Don't use them in production. +::: + +`experimental_accessibilityOrder` indicates the order in which an assistive technology focuses descendants of this `View`. This prop takes an array of strings where each string is a [`nativeID`](view.md#nativeid) of some descendant component whose order is being defined. This prop does not enable accessibility itself, each referenced component still needs to be accessible by setting [`accessible`](view.md#accessible) to true. This prop is both **nestable** and **exhaustive** meaning + +* If `experimental_accessibilityOrder` contains a reference to some non-accessible component, it will focus the descendants of that component in the default order. Additionally, it can also contain a reference to other components that also have an `experimental_accessibilityOrder`. +* If some component that is otherwise accessible is not directly referenced in `experimental_accessibilityOrder`, or nested within some container directly referenced in `experimental_accessibilityOrder`, then it will not be accessible. + +See the [accessibility guide](accessibility.md#experimental_accessibilityorder) for more information. + +| Type | +| ------- | +| array of strings | + +--- + ### `focusable`
Android
Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard. diff --git a/docs/virtualview.md b/docs/virtualview.md index 961106e3cc1..a75c8c1a18e 100644 --- a/docs/virtualview.md +++ b/docs/virtualview.md @@ -3,7 +3,7 @@ id: virtualview title: VirtualView ⚗️ --- -:::important +:::important Experimental ⚗️ **This API is experimental.** Experimental APIs may contain bugs and are likely to change in a future version of React Native. Don't use them in production. ::: From ea302c82f62947ac859ffe36fb6fcdcb6da2abfc Mon Sep 17 00:00:00 2001 From: Joe Vilches Date: Wed, 27 Aug 2025 12:23:31 -0400 Subject: [PATCH 3/3] lints --- docs/accessibility.md | 5 ++--- docs/view.md | 8 ++++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/accessibility.md b/docs/accessibility.md index 02a30004d38..e4262af6dae 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -381,7 +381,7 @@ then the new order will be `B` then `A`, even though `C` is still in `experiment ``` -The order of the above example would be `B`, `C`, `A`. `D` will never get focused. In this sense `experimental_accessibilityOrder` is *exhaustive*. +The order of the above example would be `B`, `C`, `A`. `D` will never get focused. In this sense `experimental_accessibilityOrder` is _exhaustive_. There are still valid reasons to include an non-accessible component in `experimental_accessibilityOrder`. Consider @@ -397,7 +397,7 @@ There are still valid reasons to include an non-accessible component in `experim ``` -The focus order will be `B`, `D`, `E`, `F`, `A`. Even though `D`, `E`, and `F` are not directly referenced in `experimental_accessibilityOrder`, `C` is directly referenced. In this instance `C` in an *accessibility container* - it contains accessible elements, but is not accessible itself. If an accessibility container is referenced in `experimental_accessibilityOrder` then the default order of the elements it contains is applied. In this sense `experimental_accessibilityOrder` is *nestable*. +The focus order will be `B`, `D`, `E`, `F`, `A`. Even though `D`, `E`, and `F` are not directly referenced in `experimental_accessibilityOrder`, `C` is directly referenced. In this instance `C` in an _accessibility container_ - it contains accessible elements, but is not accessible itself. If an accessibility container is referenced in `experimental_accessibilityOrder` then the default order of the elements it contains is applied. In this sense `experimental_accessibilityOrder` is _nestable_. `experimental_accessibilityOrder` can also reference another component with `experimental_accessibilityOrder` @@ -431,7 +431,6 @@ A component cannot be both an accessibility container and an accessibility eleme The focus order would be `B`, `C`, `A`. `D`, `E`, and `F` are no longer in a container, so the exhaustive nature of `experimental_accessibilityOrder` means they will be excluded. - ### `importantForAccessibility`
Android
In the case of two overlapping UI components with the same parent, default accessibility focus can have unpredictable behavior. The `importantForAccessibility` property will resolve this by controlling if a view fires accessibility events and if it is reported to accessibility services. It can be set to `auto`, `yes`, `no` and `no-hide-descendants` (the last value will force accessibility services to ignore the component and all of its children). diff --git a/docs/view.md b/docs/view.md index e4a0ce78a9a..b205edc9d54 100644 --- a/docs/view.md +++ b/docs/view.md @@ -391,13 +391,13 @@ Setting to false prevents direct children of the view from being removed from th `experimental_accessibilityOrder` indicates the order in which an assistive technology focuses descendants of this `View`. This prop takes an array of strings where each string is a [`nativeID`](view.md#nativeid) of some descendant component whose order is being defined. This prop does not enable accessibility itself, each referenced component still needs to be accessible by setting [`accessible`](view.md#accessible) to true. This prop is both **nestable** and **exhaustive** meaning -* If `experimental_accessibilityOrder` contains a reference to some non-accessible component, it will focus the descendants of that component in the default order. Additionally, it can also contain a reference to other components that also have an `experimental_accessibilityOrder`. -* If some component that is otherwise accessible is not directly referenced in `experimental_accessibilityOrder`, or nested within some container directly referenced in `experimental_accessibilityOrder`, then it will not be accessible. +- If `experimental_accessibilityOrder` contains a reference to some non-accessible component, it will focus the descendants of that component in the default order. Additionally, it can also contain a reference to other components that also have an `experimental_accessibilityOrder`. +- If some component that is otherwise accessible is not directly referenced in `experimental_accessibilityOrder`, or nested within some container directly referenced in `experimental_accessibilityOrder`, then it will not be accessible. See the [accessibility guide](accessibility.md#experimental_accessibilityorder) for more information. -| Type | -| ------- | +| Type | +| ---------------- | | array of strings | ---