A11y

Full documentation content.

<page path="/introduction" title="Introduction"><![CDATA[URL: https://a11y.docs.pmnd.rs/introduction
Description: Quick start about how to make your WebGL accessible with @react-three/a11y and react-three-fiber


<p align="center">
  <img src="react-three-a11y.jpg" />
</p>

@react-three/a11y brings accessibility to webGL with easy-to-use react-three-fiber components:

- Focus and focus indication
- Tab index and keyboard navigation
- Screen reader support and alt-text
- Roles and cursor shapes
- Descriptive links

You can try a [live demo here](https://n4rzi.csb.app).
Open it with your favourite assistive tech to test it out !

```bash
npm install @react-three/a11y
```

## Quick overview to get started

### The A11yAnnouncer component

First, place the A11yAnnouncer component next to the R3F Canvas component. This component is critical since it manage some screen-reader features.

```jsx
import { Canvas } from '@react-three/fiber';
import { A11yAnnouncer } from '@react-three/a11y';

function App() {
  return (
    <>
      <Canvas />
      <A11yAnnouncer />
    </>
  );
}
```

### Then wrap components you want to make accessible with the A11y component

To add accessibility features to your scene you'll have to wrap components you want to make focusable with the `A11y` component:

```jsx
import { A11y } from '@react-three/a11y'
[...]
<A11y>
  <MyComponent />
</A11y>
```

`MyComponent` can now receive focus. More accurately, the emulated "focus" will be handled at the `A11y` components which acts as a provider
for children to access its state. But even if objects are focusable, nothing will be displayed or shown by default.

## Call function on focus

The `focusCall` prop of `A11y` will be called each time this component receives focus (usually through tab navigation).

```jsx
<A11y role="content" focusCall={()=> console.log("in focus")} ... />
```

## Call function on click / keyboard Click

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

```jsx
<A11y role="button" actionCall={()=> console.log("clicked")} ... />
```

## Provide a description of the currently focused / hovered element

When using the `description` prop in combination with the `role` prop, the `A11y` component will provide a description to the screen reader users on focus/hover.
Optionally, you can also show the description to the user on hover by setting `showAltText={true}`.

```jsx
// Reads "A rotating red square" to screen readers on focus / hover while also showing it on mouseover
<A11y role="content" description="A rotating red square" showAltText ... />
// Reads "Button, open menu + (description on how to activate depending on the screen reader)" to screen readers on focus / hover
<A11y role="button" description="open menu" actionCall={()=>{someFunction()}} ... />
```

## The four roles of the A11y component

Like in HTML, you can focus different kind of elements and expect different things depending on what you're focusing.

#### Content

```jsx
<A11y role="content" ... />
```

Uses the `default` cursor. This role is meant to provide information to screen readers or to serve as a step for a user to navigate your site using Tab for instance. It's not meant to trigger anything on click or to be activable with the Keyboard. Therefore it won't show a pointer cursor on hover.

[Read more about role content](/a11y/roles/content)

#### Button

```jsx
<A11y
  role="button"
  description="Send email"
  activationMsg="Sending email" ... />
```

Uses the `pointer` cursor. Special attributes: `activationMsg`.

This role is meant to emulate the behaviour of a button or a toggleable button. It will display a cursor pointer when your cursor is over the linked 3D object. It will call a function on click but also on any kind of action that would trigger a focused button (Enter, Double-Tap, ...). It is also actionable by user using a screen reader.

[Read more about role button](/a11y/roles/button)

#### ToggleButton

By using the role togglebutton, you'll emulate a button with two state that will have the `aria-pressed` attribute.
You'll then be able to use the deactivationMsg property in addition to the usual description and activationMsg properties.

```jsx
<A11y
  role="togglebutton"
  description="Dark theme "
  activationMsg="Switched to dark theme"
  deactivationMsg="Switched to light theme" ... />
```

Special attributes: `deactivationMsg`

[Read more about role ToggleButton](/a11y/roles/togglebutton)

#### Link

```jsx
<A11y role="link" href="https://url.com" ... />
```

Uses the `pointer` cursor. Special attributes: `href`.

This role is meant to emulate the behaviour of a regular html link. It should be used in combination with something that will trigger navigation on click.

> [!NOTE]
> Don't forget to provide the href attribute as it is required for screen readers to read it correctly! - It will have no effect on the navigation, it's just used as information

[Read more about role link](/a11y/roles/link)

## Screen Reader Support

In order to provide informations to screen reader users and use this package at its full potential, fill the `description` prop of all your `A11y` components and use the appropriate `role` prop on each of them.

### Use of section

For screen readers, it might be useful to provide additional information on how to use some unconventional UI.
You can do it by wrapping the concerned part of your code relative to this UI in the A11ySection like so.

```jsx
<A11ySection
  label="Shape carousel"
  description="This carousel contains 5 shapes. Use the Previous and Next buttons to cycle through all the shapes."
>
  [...]
</A11ySection>
```

## Access user preferences

The A11yUserPreferences component is available in order to access user preferences such as

- prefers-reduced-motion
- prefers-color-scheme

Take a look at [the A11yUserPreferences page](/a11y/access-user-preferences) or the [demo](https://n4rzi.csb.app) to see it in action and how to use it. The demo will adapt to your system preferences.

## Additional Features

Use a custom tabindex with for your A11y components by providing a number to the tabIndex attribute

```jsx
<A11y tabIndex={-1} ... />
```

> [!CAUTION]
> Avoid using `tabindex` values greater than 0. Doing so makes it difficult for people who rely on assistive technology to navigate and operate page content.
> Instead, write the document with the elements in a logical sequence. More about the use of tabIndex on [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex)
]]></page>
<page path="/access-user-preferences" title="User Preferences"><![CDATA[URL: https://a11y.docs.pmnd.rs/access-user-preferences
Description: Learn how to access user preferences and how to adjust your app using react-three-fiber with @react-three-a11y


When it comes to accessibility, some users might need to have an interface as still as possible or with a preferred color scheme.

These are CSS media features and this library expose two of them

1. [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
1. [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)

While you don't necessarily require this library to access them, we provide an easy way to use them and listen to their changes.

## Setup

For that wrap your components inside the A11yUserPreferences component

```jsx
<A11yUserPreferences>
  <My3dObject />
  <MySecond3dObject />
  [...]
</A11yUserPreferences>
```

Then, you can access the preferences in each children component where you might need them.

## Reduce motions / animations for the users that request it

Some user on your website might need all animation turned off or limited to what's strictly necessary.
For those users, if your app has an animation going somewhere, consider cancelling it for those who request it.
You can do it like so.

```jsx
const My3dObject = () => {
  // this const will give you access to the user preferences
  const { a11yPrefersState } = useUserPreferences()
  const mesh = useRef()

  // Rotate mesh every frame
  useFrame(() => {
    //unless the user prefers reduced motion
    if (!a11yPrefersState.prefersReducedMotion) {
      mesh.current.rotation.x = mesh.current.rotation.y += 0.01
    }
  })

  return (
    <mesh ref={mesh}>
      <boxBufferGeometry args={[1, 1, 1]} />
      <meshStandardMaterial />
    </mesh>
  )
}
```

## Adapt colour scheme depending on the user preference

Some user on your website might need a darker / lighter theme. You can adapt your components according to it like so.

```jsx
const My3dObject = () => {
  // this const will give you access to the user preferences
  const { a11yPrefersState } = useUserPreferences()
  const mesh = useRef()

  return (
    <mesh ref={mesh}>
      <boxBufferGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={a11yPrefersState.prefersDarkScheme ? 'darkblue' : 'lightblue'} />
    </mesh>
  )
}
```

## Use the context outside and inside the r3f canvas

At the moment React context [can not be readily used between two renderers](https://github.com/pmndrs/react-three-fiber/issues/43), this is due to a problem within React.
If react-dom use the A11yUserPreferences provider, you will not be able to consume it within `<Canvas>`.

There's a ready-made solution in drei: [useContextBridge](https://github.com/pmndrs/drei#usecontextbridge) which allows you to forward contexts provided above the `<Canvas />` to be consumed within it.

You can see how it's used in the [react-three-a11y demo](https://n4rzi.csb.app)
]]></page>
<page path="/roles/content" title="Content"><![CDATA[URL: https://a11y.docs.pmnd.rs/roles/content
Description: This page will tell you all you need to know about making your content accessible in your react-three-fiber app with @react-three-a11y


## Role Content of the A11y component

This is the simplest role of all.
You should think of it as the equivalent of an image alt attribute
Whenever you have something in your canvas that is not simply decorative, you should use this role.

Imagine you're displaying some text with the [three.js TextGeometry](https://threejs.org/docs/#api/en/geometries/TextGeometry)

A user using a screen reader would not have access to the text.

Let's say the text is 'Welcome to my website', you could simply do as below.

```jsx
<A11y role="content" description="Welcome to my website">
  <Some3DComponentShowingText />
</A11y>
```

That's it !

Now if you inspect the dom of your app, you will see that a `<p>` tag has been added with your text inside.
That way, user with a screenreader will be able to read that text too.

> [!NOTE]
> For people using screen readers it will also sync some kind of focus indicator natively where your text is so people so screen readers users will know where they're currently in your page.

This role can also be used to serve as a step for a user to navigate your site using Tab for instance.
For that you would need to add the tabIndex prop and the focusCall prop like so.

```jsx
<A11y
  role="content"
  description="The second text of my site"
  tabIndex={0}
  focusCall={() => someFunction()}
>
  <SomeOther3DComponentWithText />
</A11y>
```

On focus, you could rotate the camera to show that second piece of text that would usually have required some scrolling to display.
Use it as you please but keep in mind how it might impact the accessibility.
For this example, screenreader don't trigger focus when swiping their screen so it would benefit people used to navigate through keyboard without hurting screenreader users.

It's not meant to trigger anything on click or to be activable with the Keyboard. Therefore it won't show a pointer cursor on hover.
]]></page>
<page path="/roles/button" title="Button"><![CDATA[URL: https://a11y.docs.pmnd.rs/roles/button
Description: This page will tell you all you need to know about emulating an accessible button in your react-three-fiber app with @react-three-a11y


## Role Button of the A11y component

This role is meant to emulate the behaviour of a button.
It will display a cursor pointer when your cursor is over the linked 3D object.
It will call a function on click but also on any kind of action that would trigger a focused button (Enter, Double-Tap, ...).
It is also actionnable by user using a screen reader.

```jsx
<A11y
  role="button"
  description="Send email"
  activationMsg="Sending email"
  actionCall={()=>sendEmail()}
  ... >
  <Some3DComponent />
</A11y>
```

Using it like this makes it focusable to all kind of users.

You should also use the useA11y() hook within the encapsulated components to adjust the rendering on hover and focus. Doing so greatly improve the accessibility of your page.
Take a look at this code sample to see how to use it.
You can also play with it in [this demo](https://n4rzi.csb.app)

```jsx
function Some3DComponent() {
  const a11y = useA11y()
  return (
    <mesh>
      <boxBufferGeometry />
      <meshStandardMaterial
        metalness={1}
        roughness={0.8}
        color={a11y.focus || a11y.hover ? '#cc66dd' : '#ffffff'}
        emissive={a11y.focus ? '#cc4444' : a11y.hover ? '#339922' : '#003399'}
      />
    </mesh>
  )
}
```

You could also specify the optional prop `activationMsg`.
The message withinh activationMsg will be announced by screenreader when the button is activated.
]]></page>
<page path="/roles/togglebutton" title="ToggleButton"><![CDATA[URL: https://a11y.docs.pmnd.rs/roles/togglebutton
Description: This page will tell you all you need to know about emulating an accessible togglable button in your react-three-fiber app with @react-three-a11y


## Role ToggleButton of the A11y component

This is mostly the same as the [button role](/a11y/roles/button).
The difference is that this button will have the aria-pressed attribute and that you'll be able to use the following deactivationMsg property in addition to the usual description and activationMsg properties.

Since this role is meant to emulate the behaviour of togglable button.
It will display a cursor pointer when your cursor is over the linked 3D object.
It will call a function on click but also on any kind of action that would trigger a focused button (Enter, Double-Tap, ...).
It is also actionnable by user using a screen reader.

```jsx
<A11y
  role="togglebutton"
  description="Dark theme"
  startPressed={false}
  actionCall="()=>switchTheme()"
  ...>
  <Some3DComponent />
</A11y>
```

Using it like this makes it focusable to all kind of users.

> [!NOTE]
> You might have noticed the startPressed prop. Depending on your need, you might want to have your button starting in a pressed state. This is what this prop is for.

You should also use the useA11y() hook within the encapsulated components to adjust the rendering on hover and focus and pressed state. Doing so greatly improve the accessibility of your page.
Take a look at this code sample to see how to use it.
You can also play with it in [this demo](https://n4rzi.csb.app)

```jsx
function Some3DComponent() {
  const a11y = useA11y(); // access pressed, hover and focus
  return (
    <mesh>
      <boxBufferGeometry />
      <meshStandardMaterial
        metalness={1}
        roughness={0.8}
        color={a11y.focus || a11y.hover ? '#cc66dd' : '#ffffff'}
        emissive={a11y.focus ? '#cc4444' : a11y.hover ? '#339922' : '#003399'}
      />
    </mesh>
  );
}
```

You could also specify the optional prop `activationMsg` and `deactivationMsg`.
Respective message will be announced by screenreader when the button is activated / deactivated.
]]></page>
<page path="/roles/link" title="Link"><![CDATA[URL: https://a11y.docs.pmnd.rs/roles/link
Description: This page will tell you all you need to know about emulating an accessible link in your react-three-fiber app with @react-three-a11y


## Role Link of the A11y component

This role is fairly straightforward
You should think of it as the equivalent of an html link "a" tag
Since it's meant to emulate the behaviour of a regular html link. It should be used in combination with something that will trigger navigation on click.

```jsx
<A11y
  role="link"
  href="/page"
  actionCall={() => {
    router.push(`/page`);
  }}
>
  <Some3DComponent />
</A11y>
```

Using it like this makes it focusable to all kind of users. It will also show a pointer on mouse over.

You should also use the useA11y() hook within the encapsulated components to adjust the rendering on hover and focus. Doing so greatly improve the accessibility of your page.
Take a look at this code sample to see how to use it.
You can also play with it in [this demo](https://n4rzi.csb.app)

```jsx
function Some3DComponent() {
  const a11y = useA11y();
  return (
    <mesh>
      <boxBufferGeometry />
      <meshStandardMaterial
        metalness={1}
        roughness={0.8}
        color={a11y.focus || a11y.hover ? '#cc66dd' : '#ffffff'}
        emissive={a11y.focus ? '#cc4444' : a11y.hover ? '#339922' : '#003399'}
      />
    </mesh>
  );
}
```

> [!IMPORTANT]
> Don't forget to provide the `href` attribute as he is required for screen readers to read it correctly!
> It will have no effect on the navigation, it's just used as information
]]></page>
<page path="/advanced/how-it-works" title="How does it work?"><![CDATA[URL: https://a11y.docs.pmnd.rs/advanced/how-it-works
Description: This is an advanced guide on the inner workings of @react-three/a11y, if you are just getting started, take a look at our introduction!


This library is pretty simple, if you're curious about how it works you can read the following information and look at the internals.

@react-three/a11y purpose is to manage the accessibility part of what is inside your canvas by syncing semantic DOM absolutely positioned over what's currently visible in your page.

Basically when you add the A11y component with a role, react-three-a11y will append the corresponding HTML tag to your document.<br />

- role="link" => a
- role="button" => button
- role="content" => p
- role="togglebutton" => button ( + aria-pressed )

The position is synced by a minimalist fork of the [Drei Html component](/drei/misc/html)

Inside an A11y component, you can access the hover, focused and pressed state through the useA11y() hook.
This hook returns the context of the A11y component.

The A11yAnnouncer is used to communicate with screen readers through a div only visible to screen readers.
It uses a [zustand](/zustand) store to update the div with each new message.
The div is roughly like this.

```html
<div aria-atomic="true" aria-live="polite">{message}</div>
```

The A11ySection component appends an HTML section in which a p element describe the content of the section.
Wrapped around some A11y components, it will cause the HTML from those component to be inside the section.

You would then have a generated DOM that could look something like this.

```html
<section aria-label="label">
  <p>description</p>
  <button></button>
  <p></p>
  <button></button>
</section>
```

For the A11yUserPreferences component, it simply exposes through a context the state of prefers-color-scheme and prefers-reduced-motion media queries.
It watches for change through

```javascript
window.matchMedia('(prefers-reduced-motion: reduce)')
window.matchMedia('(prefers-color-scheme: dark)')
```
]]></page>
<page path="/advanced/gotchas" title="Gotchas"><![CDATA[URL: https://a11y.docs.pmnd.rs/advanced/gotchas
Description: Things that could catch you off guard


### Position of the accessible dom causing wrong hover detection

In the demo, you may have noticed in App.js that the component ToggleButton is wrapped in an A11y component that use the prop `a11yElStyle` like so

```jsx
<A11y
  role="togglebutton"
  description="Light intensity"
  actionCall={() => (state.dark = !snap.dark)}
  activationMsg="Lower light disabled"
  deactivationMsg="Lower light enabled"
  a11yElStyle={{ marginLeft: '-40px' }}
>
  <ToggleButton position={[0, -3, 9]} />
</A11y>
```

Why is that ?

In order to make this "donut" accessible as a button react-three-a11y will keep an html button over it.

If we inspect the DOM, you should see something roughly like this for the above example.

```html
<button aria-pressed="false">Light intensity</button>
```

By default this button is positioned in the center of your 3D object which would cause it to work like this.

1- Mouse is not over

<p align="middle">
  <img alt="" height="200" src="beforehoverdefault.png" />
</p>

2- Mouse is over the donut, color change is triggered and the cursor pointer is displayed

<p align="middle">
  <img alt="" height="200" src="hoverdefaultout.png" />
</p>

3- Mouse is not over the donut, but the color change is still triggered as is the cursor pointer

<p align="middle">
  <img alt="" height="200" src="hoverdefault.png" />
</p>

If we display the button we can see that it's caused by the button being positioned in the middle of the donut

<p align="middle">
  <img alt="" height="200" src="hoverdefaultbecause.png" />
</p>

4- If we add `a11yElStyle={{ marginLeft: '-40px' }}` to the A11y component, the button is moved to the left and not in the center of the donut anymore

<p align="middle">
  <img alt="" height="200" src="hoverfixbecause.png" />
</p>

5- And as we can see, it fixes our issue. The cursor is default and no color change while the cursor is in the hole of the donut.

<p align="middle">
  <img alt="" height="200" src="hoverfix.png" />
</p>
]]></page>