### Install @react-three/a11y

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Installs the @react-three/a11y package using npm.

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

--------------------------------

### Basic Scene Setup

Source: https://github.com/pmndrs/react-three-a11y/blob/main/example/index.html

Demonstrates the fundamental setup of a Three.js scene with react-three-a11y enabled. This includes setting up the canvas, camera, and a simple mesh, along with the necessary accessibility attributes.

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import { Canvas } from '@react-three/fiber';
import { Box } from '@react-three/drei';
import { useA11y } from '@react-three/a11y';

function Scene() {
  const meshRef = React.useRef();
  const a11yProps = useA11y('A simple cube', { /* accessibility props */ });

  return (
    <Box ref={meshRef} {...a11yProps} args={[1, 1, 1]} position={[0, 0, 0]}>
      <meshStandardMaterial attach="material" color="hotpink" />
    </Box>
  );
}

ReactDOM.render(
  <Canvas>
    <ambientLight intensity={0.5} />
    <pointLight position={[10, 10, 10]} />
    <Scene />
  </Canvas>,
  document.getElementById('root')
);
```

--------------------------------

### Basic Setup with A11yAnnouncer

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Demonstrates the basic setup by placing the A11yAnnouncer component next to the R3F Canvas component. The A11yAnnouncer is crucial for managing screen-reader features.

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

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

--------------------------------

### Install @react-three/a11y

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Installs the @react-three/a11y package using npm. This is the first step to integrating accessibility features into your react-three-fiber application.

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

--------------------------------

### Setup A11yUserPreferences

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/access-user-preferences.mdx

Wrap your components with A11yUserPreferences to provide accessibility preference state to nested components. This allows children to access and react to user preferences.

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

--------------------------------

### Generated DOM Example

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/advanced/how-it-works.mdx

Illustrates a potential HTML DOM structure generated by the A11ySection component, which wraps other A11y components to create accessible sections with descriptions and interactive elements.

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

--------------------------------

### A11y ToggleButton Example

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/roles/togglebutton.mdx

Demonstrates how to use the A11y component with the 'togglebutton' role to create an accessible togglable button in a react-three-fiber application. It includes properties for accessibility descriptions and actions.

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

--------------------------------

### Providing Descriptions for Screen Readers

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Demonstrates how to use the `description` prop, optionally with `showAltText={true}`, to provide descriptive text for screen readers and on hover for focused or hovered elements.

```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()}} ... />
```

--------------------------------

### Provide Descriptions with description and showAltText

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Enhances screen reader support by providing descriptive text for focused or hovered elements using the `description` prop. The `showAltText` prop additionally displays this description on mouseover.

```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()}} ... />
```

--------------------------------

### User Preferences Media Query Listeners

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/advanced/how-it-works.mdx

Shows the JavaScript code used by the A11yUserPreferences component to monitor changes in user preferences for reduced motion and color scheme. It utilizes the window.matchMedia API.

```javascript
window.matchMedia('(prefers-reduced-motion: reduce)')
window.matchMedia('(prefers-color-scheme: dark)')
```

--------------------------------

### Using useA11y Hook for Visual Feedback

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/roles/button.mdx

Shows how to use the useA11y hook within a 3D component to provide visual feedback on hover and focus states. This enhances the accessibility by changing the component's appearance based on user interaction.

```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>
  )
}
```

--------------------------------

### Making Components Accessible with A11y

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Shows how to wrap components that need accessibility features with the A11y component. This allows the wrapped components to receive focus and access the state provided by the A11y component.

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

--------------------------------

### Calling Functions on Click or Keyboard Activation

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Uses the `actionCall` prop of the A11y component to trigger a function on click, keyboard activation, or other actions that would activate a focused button.

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

--------------------------------

### A11y Roles: Button

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Defines the 'button' role for the A11y component, which uses a pointer cursor and emulates button behavior. It supports `activationMsg` and can be triggered by click, keyboard actions, or screen readers.

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

--------------------------------

### Interactive Elements

Source: https://github.com/pmndrs/react-three-a11y/blob/main/example/index.html

Shows how to make objects in the scene interactive and accessible. This involves adding event handlers and ARIA attributes to elements, allowing users to interact with them via keyboard or assistive technologies.

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import { Canvas } from '@react-three/fiber';
import { Box } from '@react-three/drei';
import { useA11y } from '@react-three/a11y';

function InteractiveBox() {
  const meshRef = React.useRef();
  const a11yProps = useA11y('Clickable cube', {
    role: 'button',
    action: () => alert('Cube clicked!')
  });

  return (
    <Box ref={meshRef} {...a11yProps} args={[1, 1, 1]} position={[0, 0, 0]}>
      <meshStandardMaterial attach="material" color="lightblue" />
    </Box>
  );
}

ReactDOM.render(
  <Canvas>
    <ambientLight intensity={0.5} />
    <pointLight position={[10, 10, 10]} />
    <InteractiveBox />
  </Canvas>,
  document.getElementById('root')
);
```

--------------------------------

### A11y Roles: Content

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Defines the 'content' role for the A11y component, which uses the default cursor and is intended for providing information to screen readers or as navigation steps. It is not designed to be clickable or keyboard-activable.

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

--------------------------------

### Initialize A11yAnnouncer

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Sets up the A11yAnnouncer component, which is essential for managing screen-reader features. It should be placed alongside the R3F Canvas component.

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

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

--------------------------------

### Calling Functions on Focus

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Utilizes the `focusCall` prop of the A11y component to execute a function whenever the component receives focus, typically through keyboard navigation.

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

--------------------------------

### A11y Roles: Link

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Defines the 'link' role for the A11y component, which uses a pointer cursor and emulates an HTML link. It requires the `href` attribute for screen reader information and is used in conjunction with elements that trigger navigation.

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

--------------------------------

### Basic Content Role

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/roles/content.mdx

Demonstrates the basic usage of the 'content' role for making 3D elements accessible. It wraps a 3D component and provides a descriptive text for screen readers.

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

--------------------------------

### Reacting to Reduced Motion

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/access-user-preferences.mdx

Demonstrates how to use the `useUserPreferences` hook to access the `prefersReducedMotion` state. If the user prefers reduced motion, animations are skipped to improve accessibility.

```jsx
import { useFrame } from '@react-three/fiber'
import { useUserPreferences } from '@react-three/a11y'
import { useRef } from 'react'

const My3dObject = () => {
  const { a11yPrefersState } = useUserPreferences()
  const mesh = useRef()

  useFrame(() => {
    if (!a11yPrefersState.prefersReducedMotion) {
      mesh.current.rotation.x = mesh.current.rotation.y += 0.01
    }
  })

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

--------------------------------

### Adapting Color Scheme

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/access-user-preferences.mdx

Shows how to use the `useUserPreferences` hook to access the `prefersDarkScheme` state. Components can dynamically change their appearance, such as material color, based on the user's preferred color scheme.

```jsx
import { useUserPreferences } from '@react-three/a11y'
import { useRef } from 'react'

const My3dObject = () => {
  const { a11yPrefersState } = useUserPreferences()
  const mesh = useRef()

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

--------------------------------

### useA11y Hook for Dynamic Rendering

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/roles/togglebutton.mdx

Shows how to use the useA11y hook within a 3D component to access and react to accessibility states like focus, hover, and pressed. This allows for dynamic visual feedback based on user interaction.

```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>
  );
}
```

--------------------------------

### Content Role with Focus Management

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/roles/content.mdx

Shows how to enhance the 'content' role with focus management capabilities. By adding `tabIndex` and `focusCall`, users can navigate to and interact with the element using keyboard focus, potentially triggering custom actions like camera rotation.

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

--------------------------------

### A11ySection for Screen Reader Descriptions

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Wraps UI elements to provide descriptive context for screen readers. Useful for complex or unconventional UI components like carousels.

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

--------------------------------

### A11y Component Usage with a11yElStyle

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/advanced/gotchas.mdx

Demonstrates how to use the `A11y` component with the `a11yElStyle` prop to adjust the position of the overlaid HTML element. This is crucial for correcting hover detection issues caused by the default centering of the accessible DOM element.

```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>
```

--------------------------------

### A11y Role: Button

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Sets the A11y component to 'button' role, emulating button behavior with pointer cursor on hover. It supports click and keyboard activation, and screen reader interaction. The `activationMsg` prop provides feedback on action.

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

--------------------------------

### Accessibility Attributes

Source: https://github.com/pmndrs/react-three-a11y/blob/main/example/index.html

Illustrates the use of specific ARIA roles and properties to enhance the accessibility of Three.js objects. This includes defining roles, states, and properties that assistive technologies can interpret.

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import { Canvas } from '@react-three/fiber';
import { Sphere } from '@react-three/drei';
import { useA11y } from '@react-three/a11y';

function AccessibleSphere() {
  const meshRef = React.useRef();
  const a11yProps = useA11y('A sphere with custom attributes', {
    role: 'img',
    name: 'A blue sphere',
    description: 'Represents an interactive element in the scene'
  });

  return (
    <Sphere ref={meshRef} {...a11yProps} args={[1, 32, 32]} position={[2, 0, 0]}>
      <meshStandardMaterial attach="material" color="blue" />
    </Sphere>
  );
}

ReactDOM.render(
  <Canvas>
    <ambientLight intensity={0.5} />
    <pointLight position={[10, 10, 10]} />
    <AccessibleSphere />
  </Canvas>,
  document.getElementById('root')
);
```

--------------------------------

### A11y Role Link

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Emulates an HTML link for accessibility. Requires an 'href' attribute for screen readers and should be paired with an event handler for navigation. Uses the 'pointer' cursor.

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

--------------------------------

### Handle Focus Events with focusCall

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Uses the `focusCall` prop on the A11y component to execute a function whenever the component receives focus, typically via keyboard navigation.

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

--------------------------------

### Generated Accessible DOM Element

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/advanced/gotchas.mdx

Illustrates the HTML structure generated by the `A11y` component to provide accessibility for a 3D object. This typically involves an HTML button that mirrors the interactive state of the 3D element.

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

--------------------------------

### A11yUserPreferences Component

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Allows access to user system preferences such as 'prefers-reduced-motion' and 'prefers-color-scheme'. The demo adapts to system settings.

```jsx
// Example usage would involve importing and using A11yUserPreferences component
```

--------------------------------

### A11yAnnouncer Structure

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/advanced/how-it-works.mdx

Demonstrates the basic HTML structure used by the A11yAnnouncer component to communicate messages to screen readers. It utilizes ARIA attributes for proper announcement.

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

--------------------------------

### Handle Click and Keyboard Events with actionCall

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Utilizes the `actionCall` prop on the A11y component to trigger a function on click, keyboard activation, or other interaction events.

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

--------------------------------

### A11y Role: Content

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Configures the A11y component with the 'content' role, suitable for informational elements that don't require direct interaction. It uses the default cursor and is primarily for screen reader navigation.

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

--------------------------------

### Make Components Focusable with A11y

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Wraps components with the A11y component to enable accessibility features like focus and keyboard navigation. The A11y component acts as a provider for its children's accessibility state.

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

--------------------------------

### Accessible Button with A11y Component

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/roles/button.mdx

Demonstrates how to use the A11y component with the 'button' role to create an accessible button in a react-three-fiber application. It includes event handling for clicks and keyboard interactions, and supports screen reader announcements via activationMsg.

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

--------------------------------

### Accessible Link with Navigation

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/roles/link.mdx

Demonstrates how to create an accessible link using the A11y component with the 'link' role. It includes an actionCall prop for navigation and a nested 3D component that reacts to focus and hover states.

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

```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>
  );
}
```

--------------------------------

### A11ySection for Semantic Grouping

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

The A11ySection component allows you to semantically group parts of your UI for screen readers. It requires a 'label' for identification and a 'description' to provide context on how to interact with the grouped content. This is particularly useful for unconventional UI elements like carousels.

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

--------------------------------

### A11y Roles: ToggleButton

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

Defines the 'togglebutton' role for the A11y component, emulating a button with two states using the `aria-pressed` attribute. It supports `activationMsg` and `deactivationMsg`.

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

--------------------------------

### Custom Tab Index for A11y Components

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/introduction.mdx

You can control the tab order of A11y components by providing a 'tabIndex' prop. It is recommended to use values like -1 to allow programmatic focus or 0 for default tab order. Avoid using positive tabIndex values as they can disrupt the natural navigation flow for assistive technology users.

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

--------------------------------

### Using Context Across Renderers with useContextBridge

Source: https://github.com/pmndrs/react-three-a11y/blob/main/docs/access-user-preferences.mdx

Explains the challenge of using React context between react-dom and react-three-fiber's Canvas. It recommends using drei's `useContextBridge` to forward contexts from above the Canvas to be consumable within it.

```jsx
/*
  Example usage with useContextBridge (from drei):
  import { Canvas } from '@react-three/fiber'
  import { useContextBridge } from '@react-three/drei'
  import { A11yUserPreferences } from '@react-three/a11y'

  const ContextBridge = useContextBridge(A11yUserPreferences)

  function App() {
    return (
      <A11yUserPreferences>
        <Canvas>
          <ContextBridge>
            <My3dObject />
          </ContextBridge>
        </Canvas>
      </A11yUserPreferences>
    )
  }
*/

// See the react-three-a11y demo for a practical example:
// https://n4rzi.csb.app
```

--------------------------------

### Custom TabIndex with A11y

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Enables custom tab index management for A11y components. Avoid using values greater than 0 to maintain logical navigation order for assistive technologies.

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

--------------------------------

### A11y Role: ToggleButton

Source: https://github.com/pmndrs/react-three-a11y/blob/main/README.md

Implements a toggle button with two states using the 'togglebutton' role. It manages the `aria-pressed` attribute and supports `activationMsg` for the active state and `deactivationMsg` for the inactive state.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.