Skip to content

Commit 6a74cfa

Browse files
joevilchesjoevilches
committed
documentation for experimental_accessibilityOrder
1 parent c132502 commit 6a74cfa

1 file changed

Lines changed: 108 additions & 0 deletions

File tree

‎docs/accessibilityorder.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
id: accessibilityorder
3+
title: experimental_accessibilityOrder ⚗️
4+
---
5+
6+
:::important
7+
**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.
8+
:::
9+
10+
`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
11+
12+
* 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`.
13+
* 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.
14+
15+
| Type |
16+
| ------- |
17+
| array of strings |
18+
19+
## Guide
20+
21+
:::note
22+
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.
23+
:::
24+
25+
`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:
26+
27+
```
28+
<View accessibilityOrder={['B', 'C', 'A']}>
29+
<View accessible={true} nativeID="A"/>
30+
<View accessible={true} nativeID="B"/>
31+
<View accessible={true} nativeID="C"/>
32+
</View>
33+
```
34+
35+
Assistive technologies will focus the `View` with `nativeID` of `“B”`, then `“C”`, then `“A”`.
36+
37+
`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
38+
39+
```
40+
<View accessibilityOrder={['B', 'C', 'A']}>
41+
<View accessible={true} nativeID="A"/>
42+
<View accessible={true} nativeID="B"/>
43+
<View nativeID="C"/>
44+
</View>
45+
```
46+
47+
then the new order will be `“B”` then `“A”`, even though `“C”` is still in `experimental_accessibilityOrder`.
48+
49+
`experimental_accessibilityOrder` will “turn off” accessibility of components it doesn’t reference, however.
50+
51+
```
52+
<View accessibilityOrder={['B', 'C', 'A']}>
53+
<View accessible={true} nativeID="A"/>
54+
<View accessible={true} nativeID="B"/>
55+
<View accessible={true} nativeID="C"/>
56+
<View accessible={true} nativeID="D"/>
57+
</View>
58+
```
59+
60+
The order of the above example would be `“B”`, `“C”`, `“A”`. `“D”` will never get focused. In this sense `experimental_accessibilityOrder` is *exhaustive*.
61+
62+
There are still valid reasons to include an non-accessible component in `experimental_accessibilityOrder`. Consider
63+
64+
```
65+
<View accessibilityOrder={['B', 'C', 'A']}>
66+
<View accessible={true} nativeID="A"/>
67+
<View accessible={true} nativeID="B"/>
68+
<View nativeID="C">
69+
<View accessible={true} nativeID="D"/>
70+
<View accessible={true} nativeID="E"/>
71+
<View accessible={true} nativeID="F"/>
72+
</View>
73+
</View>
74+
```
75+
76+
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*.
77+
78+
`experimental_accessibilityOrder` can also reference another component with `experimental_accessibilityOrder`
79+
80+
```
81+
<View accessibilityOrder={['B', 'C', 'A']}>
82+
<View accessible={true} nativeID="A"/>
83+
<View accessible={true} nativeID="B"/>
84+
<View nativeID="C" accessibilityOrder={['F', 'E', 'D']}>
85+
<View accessible={true} nativeID="D"/>
86+
<View accessible={true} nativeID="E"/>
87+
<View accessible={true} nativeID="F"/>
88+
</View>
89+
</View>
90+
```
91+
92+
The focus order will be `“B”`, `“F”`, `“E”`, `“D”`, `“A”`.
93+
94+
A component cannot be both an accessibility container and an accessibility element (`accessible={true}`). So if we have
95+
96+
```
97+
<View accessibilityOrder={['B', 'C', 'A']}>
98+
<View accessible={true} nativeID="A"/>
99+
<View accessible={true} nativeID="B"/>
100+
<View accessible={true} nativeID="C" accessibilityOrder={['F', 'E', 'D']}>
101+
<View accessible={true} nativeID="D"/>
102+
<View accessible={true} nativeID="E"/>
103+
<View accessible={true} nativeID="F"/>
104+
</View>
105+
</View>
106+
```
107+
108+
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.

0 commit comments

Comments
 (0)