@react-three/a11y Documentation

The library manages accessibility by syncing semantic DOM elements that are absolutely positioned over the visible content in your page. When you use the A11y component with a specific role, the library appends the corresponding HTML tag to your document to ensure screen readers can interact with the 3D scene elements.

Role to HTML Mapping:

• role="link" $\rightarrow$ <a>
• role="button" $\rightarrow$ <button>
• role="content" $\rightarrow$ <p>
• role="togglebutton" $\rightarrow$ <button> (with aria-pressed attribute)

Because React context cannot be readily shared between react-dom and the react-three-fiber renderer, providing A11yUserPreferences outside of the <Canvas /> component will prevent it from being consumed by components inside the <Canvas />.

To bridge this gap, use the useContextBridge hook from @react-three/drei. This allows you to forward the context provided in the DOM layer into the R3F canvas layer.

The A11yAnnouncer component is used to send messages to screen readers via a div that is only visible to assistive technologies. It utilizes a zustand store to update the content of a live region.

The underlying HTML structure used for announcements is:

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

The role="content" is the simplest role in the @react-three/a11y component. It is intended for non-decorative elements in your canvas, acting similarly to an alt attribute for images.

When you use this role, the library injects a <p> tag into the DOM containing your description. This allows screen reader users to perceive the text or meaning of the 3D object. It also provides a native focus indicator that syncs with the element's position in the DOM, helping screen reader users understand their location on the page.

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

To make a 3D object focusable and accessible, wrap it with the A11y component. The A11y component acts as a provider for its children, handling emulated focus state. Note that by default, nothing will be visually displayed or shown unless you configure props like showAltText or specific roles.

import { A11y } from '@react-three/a11y'

// ...
<A11y>
  <MyComponent />
</A11y>

You can adapt the visual appearance of your 3D objects (like material colors) based on the user's preferred color scheme using a11yPrefersState.prefersDarkScheme.

const My3dObject = () => {
  // access 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>
  )
}

Install the package via npm to start adding accessibility features to your WebGL/react-three-fiber scenes.

npm install @react-three/a11y

To use accessibility features in your React Three Fiber project, install the package using npm.

npm install @react-three/a11y

To make a 3D object behave like an accessible button, wrap it in the <A11y /> component and set the role prop to "button".

When using `role="button":

• The cursor changes to a pointer when hovering over the object.
• The actionCall function is triggered on click, as well as on keyboard actions (like Enter) or gestures (like Double-Tap).
• The element becomes actionable for screen reader users.
• You can provide a description to explain the button's purpose and an activationMsg to announce a specific message when the button is activated.

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

To respect users who request reduced motion, use the useUserPreferences hook to access a11yPrefersState.prefersReducedMotion. You can use this boolean to conditionally skip animations or frame-based updates inside useFrame.

const My3dObject = () => {
  // access 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>
  )
}