Skip to content

Commit f2ff559

Browse files
joevilchesjoevilches
authored
documentation for experimental_accessibilityOrder (#4752)
* documentation for experimental_accessibilityOrder * bake documentation into existing pages * lints
1 parent da3ce74 commit f2ff559

File tree

3 files changed

+114
-1
lines changed

3 files changed

+114
-1
lines changed

‎docs/accessibility.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -337,6 +337,100 @@ Indicates whether a selectable element is currently selected or not.
337337
| ------- |
338338
| boolean |
339339

340+
### `experimental_accessibilityOrder`
341+
342+
:::important Experimental ⚗️
343+
**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.
344+
:::
345+
:::note
346+
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.
347+
:::
348+
349+
`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:
350+
351+
```
352+
<View experimental_accessibilityOrder={['B', 'C', 'A']}>
353+
<View accessible={true} nativeID="A"/>
354+
<View accessible={true} nativeID="B"/>
355+
<View accessible={true} nativeID="C"/>
356+
</View>
357+
```
358+
359+
Assistive technologies will focus the `View` with `nativeID` of `B`, then `C`, then `A`.
360+
361+
`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
362+
363+
```
364+
<View experimental_accessibilityOrder={['B', 'C', 'A']}>
365+
<View accessible={true} nativeID="A"/>
366+
<View accessible={true} nativeID="B"/>
367+
<View nativeID="C"/>
368+
</View>
369+
```
370+
371+
then the new order will be `B` then `A`, even though `C` is still in `experimental_accessibilityOrder`.
372+
373+
`experimental_accessibilityOrder` will “turn off” accessibility of components it doesn’t reference, however.
374+
375+
```
376+
<View experimental_accessibilityOrder={['B', 'C', 'A']}>
377+
<View accessible={true} nativeID="A"/>
378+
<View accessible={true} nativeID="B"/>
379+
<View accessible={true} nativeID="C"/>
380+
<View accessible={true} nativeID="D"/>
381+
</View>
382+
```
383+
384+
The order of the above example would be `B`, `C`, `A`. `D` will never get focused. In this sense `experimental_accessibilityOrder` is _exhaustive_.
385+
386+
There are still valid reasons to include an non-accessible component in `experimental_accessibilityOrder`. Consider
387+
388+
```
389+
<View experimental_accessibilityOrder={['B', 'C', 'A']}>
390+
<View accessible={true} nativeID="A"/>
391+
<View accessible={true} nativeID="B"/>
392+
<View nativeID="C">
393+
<View accessible={true} nativeID="D"/>
394+
<View accessible={true} nativeID="E"/>
395+
<View accessible={true} nativeID="F"/>
396+
</View>
397+
</View>
398+
```
399+
400+
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_.
401+
402+
`experimental_accessibilityOrder` can also reference another component with `experimental_accessibilityOrder`
403+
404+
```
405+
<View experimental_accessibilityOrder={['B', 'C', 'A']}>
406+
<View accessible={true} nativeID="A"/>
407+
<View accessible={true} nativeID="B"/>
408+
<View nativeID="C" experimental_accessibilityOrder={['F', 'E', 'D']}>
409+
<View accessible={true} nativeID="D"/>
410+
<View accessible={true} nativeID="E"/>
411+
<View accessible={true} nativeID="F"/>
412+
</View>
413+
</View>
414+
```
415+
416+
The focus order will be `B`, `F`, `E`, `D`, `A`.
417+
418+
A component cannot be both an accessibility container and an accessibility element (`accessible={true}`). So if we have
419+
420+
```
421+
<View experimental_accessibilityOrder={['B', 'C', 'A']}>
422+
<View accessible={true} nativeID="A"/>
423+
<View accessible={true} nativeID="B"/>
424+
<View accessible={true} nativeID="C" experimental_accessibilityOrder={['F', 'E', 'D']}>
425+
<View accessible={true} nativeID="D"/>
426+
<View accessible={true} nativeID="E"/>
427+
<View accessible={true} nativeID="F"/>
428+
</View>
429+
</View>
430+
```
431+
432+
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.
433+
340434
### `importantForAccessibility` <div className="label android">Android</div>
341435

342436
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).

‎docs/view.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -383,6 +383,25 @@ Setting to false prevents direct children of the view from being removed from th
383383

384384
---
385385

386+
### `experimental_accessibilityOrder`
387+
388+
:::important Experimental ⚗️
389+
**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.
390+
:::
391+
392+
`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
393+
394+
- 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`.
395+
- 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.
396+
397+
See the [accessibility guide](accessibility.md#experimental_accessibilityorder) for more information.
398+
399+
| Type |
400+
| ---------------- |
401+
| array of strings |
402+
403+
---
404+
386405
### `focusable` <div className="label android">Android</div>
387406

388407
Whether this `View` should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard.

‎docs/virtualview.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ id: virtualview
33
title: VirtualView ⚗️
44
---
55

6-
:::important
6+
:::important Experimental ⚗️
77
**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.
88
:::
99

0 commit comments

Comments
 (0)