diff --git a/docs/accessibility.md b/docs/accessibility.md index 0b42f659a64..e4262af6dae 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -337,6 +337,100 @@ 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/view.md b/docs/view.md index f26406d2412..b205edc9d54 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. :::