Skip to content

Commit 6b60f36

Browse files
drcmdadrcmda
authored
Update README.md
1 parent 5b3374e commit 6b60f36

File tree

1 file changed

+47
-121
lines changed

1 file changed

+47
-121
lines changed

‎README.md

Lines changed: 47 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -4,130 +4,82 @@
44
[![Downloads](https://img.shields.io/npm/dt/@react-three/a11y.svg?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@react-three/a11y)
55
[![Discord Shield](https://img.shields.io/discord/740090768164651008?style=flat&colorA=000000&colorB=000000&label=discord&logo=discord&logoColor=ffffff)](https://discord.gg/ZZjjNvJ)
66

7+
```bash
8+
npm install @react-three/a11y
9+
```
10+
711
`@react-three/a11y` brings accessibility to WebGL, with easy to use components [react-three-fiber](https://github.com/pmndrs/react-three-fiber) components to enable focus indication, keyboard tab navigation, and screen reader support.
812

913
# How to use
1014

11-
## Initial setup
15+
First, place the `A11yAnnouncer` component next to the R3F Canvas component. This is critical, because it will manage the screen-reader and help emulate focus!
1216

13-
Install the @react-three/a11y package
17+
```jsx
18+
import { A11yAnnouncer } from '@react-three/a11y'
1419

15-
```bash
16-
npm install @react-three/a11y
20+
function App() {
21+
return (
22+
<>
23+
<Canvas />
24+
<A11yAnnouncer />
25+
</>
26+
)
27+
}
1728
```
1829

19-
Now, you'll have to import the `A11yAnnouncer` component. We usually place it next to the R3F Canvas component.
30+
To add some accessibility features to your scene you'll have to wrap objects you want to make focusable with the `A11y` component:
2031

2132
```jsx
22-
import { A11yAnnouncer } from "@react-three/a11y"
23-
{...}
24-
<Canvas>
25-
{...}
26-
</Canvas>
27-
<A11yAnnouncer />
28-
```
33+
import { A11y } from '@react-three/a11y'
2934

30-
This will both help us emulate focus inside the canvas and provide some text to screen readers when necessary.
31-
32-
To add some accessibility features to your 3D Objects/Groups you'll have to wrap the 3D objects you want to make focusable with the `A11y` component:
33-
34-
```jsx
35-
import { A11yAnnouncer, A11y } from "@react-three/a11y"
36-
37-
<Canvas>
38-
{...}
39-
<A11y>
40-
<My3DComponent />
41-
</A11y>
42-
{...}
43-
<A11y>
44-
<AGroupOf3DComponent />
45-
</A11y>
46-
{...}
47-
</Canvas>
48-
<A11yAnnouncer />
35+
<A11y>
36+
<MyComponent />
37+
</A11y>
4938
```
5039

51-
At this point both _My3DComponent_ and _AGroupOf3DComponent_ can receive focus.
52-
More accurately, the emulated "focus" will be on the parent `A11y` that will act as a provider and let its children access the state.
53-
But even if they're focusable, nothing will be displayed / read etc without a few more attributes.
40+
At this point both `MyComponent` can receive focus. More accurately, the emulated "focus" will be on the parent `A11y` that will act as a provider and let its children access its state. But even if objects are focusable, nothing will be displayed or read without a few more attributes.
5441

5542
## Accessing the hover, focused & pressed state
5643

5744
For each child wrapped in a `A11y` component, you can access the `focus` / `hover` / `pressed` state like so:
5845

5946
```jsx
60-
import { A11yAnnouncer, A11y, useA11y } from "@react-three/a11y"
61-
62-
{...}
63-
64-
const My3DComponent = (props) {
65-
66-
//call useA11y to get the A11yContext from the provider
67-
const a11yContext = useA11y();
68-
//now you have access to a11yContext.hover, a11yContext.focus and a11yContext.pressed
47+
import { useA11y } from '@react-three/a11y'
6948

49+
function Box(props) {
50+
//useA11y gives us access to hover, focus and pressed states
51+
const a11y = useA11y()
7052
return (
7153
<mesh {...props}>
72-
<boxBufferGeometry args={[1, 1, 1]} />
73-
{/* here we'll change the material color depending on the a11yContext state */}
74-
<meshStandardMaterial color={a11yContext.hover || a11yContext.focus ? 'hotpink' : 'orange'} />
54+
<boxBufferGeometry />
55+
<meshStandardMaterial color={a11y.hover || a11y.focus ? 'hotpink' : 'orange'} />
7556
</mesh>
7657
)
7758
}
7859
```
7960

80-
In this example, the _meshStandardMaterial_ of the component _My3DComponent_ will change color if he is either focused or hovered.
81-
How you display the focus / hover information to the user is up to you! Just make sure it's intuitive for your user!
82-
8361
## The role attribute
8462

85-
Like in HTML, you can focus different kind of elements and expect different things depending on what you're focusing.
86-
That's why the `A11y` component has 3 different use cases:
63+
Like in HTML, you can focus different kind of elements and expect different things depending on what you're focusing:
8764

8865
- `role="content"` ( default ) <a href="/#content">More below </a>
89-
9066
- `role="button"` <a href="/#button">More below </a>
91-
9267
- `role="link"` <a href="/#link">More below </a>
9368

9469
## Call function on focus
9570

96-
The `focusCall` prop of `A11y` will be called each time this component receive focus ( Usually through tab navigation ).
97-
You can for instance use it in order to make sure the currently focused element is in view by adjusting its position or the moving the camera.
71+
The `focusCall` prop of `A11y` will be called each time this component receives focus (usually through tab navigation).
9872

9973
```jsx
100-
import { A11yAnnouncer, A11y } from "@react-three/a11y"
101-
102-
<Canvas>
103-
{...}
104-
<A11y role="content" focusCall={()=>{
105-
//rotate camera to show the focused element
106-
}}>
107-
<My3DComponent />
108-
</A11y>
109-
{...}
110-
</Canvas>
111-
<A11yAnnouncer />
74+
<A11y role="content" focusCall={()=> console.log("in focus")} ... />
11275
```
11376

11477
## Call function on click / keyboard Click
11578

116-
The `actionCall` prop of `A11y` will be called each time this component gets clicked, focused, keyboard activated etc..
79+
The `actionCall` prop of `A11y` will be called each time this component gets clicked, focused, keyboard activated etc.
11780

11881
```jsx
119-
import { A11yAnnouncer, A11y } from "@react-three/a11y"
120-
121-
<Canvas>
122-
{...}
123-
<A11y role="button" actionCall={()=>{
124-
alert('This button have been clicked')
125-
}}>
126-
<My3DComponent />
127-
</A11y>
128-
{...}
129-
</Canvas>
130-
<A11yAnnouncer />
82+
<A11y role="button" actionCall={()=> console.log("clicked")} ... />
13183
```
13284

13385
## Provide a description of the currenlty focused / hovered element
@@ -136,22 +88,10 @@ When using the `description` prop, the `A11y` component will provide a descripti
13688
Optionally, you can also show the description to the user on hover by setting `showAltText={true}`.
13789

13890
```jsx
139-
import { A11yAnnouncer, A11y } from "@react-three/a11y"
140-
141-
<Canvas>
142-
{...}
143-
<A11y role="content" description="A rotating red square">
144-
//will read "A rotating red square" to screen readers on focus / hover
145-
<My3DSquare />
146-
</A11y>
147-
{...}
148-
<A11y role="content" description="A bouncing blue sphere" showAltText={true}>
149-
//will read "A bouncing blue sphere" to screen readers on focus / hover while also showing it on mouseover
150-
<My3DSphere />
151-
</A11y>
152-
{...}
153-
</Canvas>
154-
<A11yAnnouncer />
91+
// Reads "A rotating red square" to screen readers on focus / hover
92+
<A11y role="content" description="A rotating red square" ... />
93+
// Reads "A bouncing blue sphere" to screen readers on focus / hover while also showing it on mouseover
94+
<A11y role="content" description="A bouncing blue sphere" showAltText ... />
15595
```
15696

15797
If your `A11y` component has the `role="button"`, you can use three more props:
@@ -161,28 +101,16 @@ If your `A11y` component has the `role="button"`, you can use three more props:
161101
- `pressedDescription`: When set, it turns your button in a togglable button. Which means it now has a on/off state. This description will replace the one passed via `description` when the toggle is active.
162102

163103
```jsx
164-
import { A11yAnnouncer, A11y } from "@react-three/a11y"
165-
166-
<Canvas>
167-
{...}
168-
<A11y role="button" description="This button will send a thank you email to the team" activationMsg="Email is sending">
169-
//will read the description on hover / focus then will read activationMsg if clicked / pressed
170-
<My3DSquare />
171-
</A11y>
172-
{...}
173-
<A11y
174-
role="button"
175-
description="This button can enable dark theme. Dark theme is off"
176-
pressedDescription="This button can disable dark theme. Dark theme is on"
177-
activationMsg="Dark theme enabled"
178-
deactivationMsg="Dark theme disabled"
179-
>
180-
//will read the description on hover / focus then will read activationMsg if turned on or deactivationMsg if tuned off
181-
<My3DSphere />
182-
</A11y>
183-
{...}
184-
</Canvas>
185-
<A11yAnnouncer />
104+
// Reads the description on hover/focus then will read activationMsg if clicked/pressed
105+
<A11y role="button" description="Sends a thank you email to the team" activationMsg="Email is sending" ... />
106+
// Reads the description on hover/focus then will read activationMsg if turned on or deactivationMsg if tuned off
107+
<A11y
108+
role="button"
109+
description="This button can enable dark theme. Dark theme is off"
110+
pressedDescription="This button can disable dark theme. Dark theme is on"
111+
activationMsg="Dark theme enabled"
112+
deactivationMsg="Dark theme disabled"
113+
... />
186114
```
187115

188116
## The three roles of the `A11y` component
@@ -226,9 +154,7 @@ In order to provide informations to screen reader users and use this package at
226154
Use a custom tabindex with for your A11y components by providing a number to the tabIndex attribute
227155

228156
```jsx
229-
<A11y tabIndex={2}>
230-
<My3DSquare />
231-
</A11y>
157+
<A11y tabIndex={2} ... />
232158
```
233159

234160
More about the use of tabIndex on <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex">developer.mozilla.org</a>

0 commit comments

Comments
 (0)