React Aria

Common errors

• TypeError: Cannot read properties of null (reading 'focus')

  cause This error often occurs when a `ref` required by a React Aria hook is not properly assigned to the corresponding DOM element, or the element is not mounted when the hook tries to interact with it.
  fix Ensure the `ref` returned by `React.useRef()` is passed to the DOM element (`ref={myRef}`) that the React Aria hook expects to control or observe. Check for conditional rendering that might cause the element to be null when the hook executes.

• Accessibility warning: 'Some element' must have a label accessible to screen readers, or you must provide an `aria-label` or `aria-labelledby` prop.

  cause React Aria ensures proper WAI-ARIA roles and attributes, but it relies on the developer to provide semantic content and labels where appropriate. This warning indicates a missing accessible name.
  fix Provide a visible label as children to the component, or explicitly add an `aria-label` or `aria-labelledby` prop to the element. For example, a button created with `useButton` needs text content or an `aria-label`.

Warnings

• gotcha React Aria provides 'headless' hooks for accessibility and interaction logic, not pre-styled visual components. Developers are responsible for providing all visual styling and the underlying DOM structure. This can be a significant mental model shift for those accustomed to traditional component libraries.
  Fix: Always remember to spread the returned props from React Aria hooks onto your DOM elements (e.g., `<button {...buttonProps} />`) and to provide a `ref` if the hook requires one.
• breaking While `react-aria` itself focuses on primitives, the introduction and evolution of `@adobe/react-spectrum` and `react-aria-components` represents different architectural approaches to building UI. Users of `@adobe/react-spectrum` (a styled component library) or `react-aria-components` (unstyled components built on `react-aria` hooks) should be aware that their APIs and usage patterns differ significantly from directly using `react-aria` hooks.
  Fix: Determine whether you need 'headless' hooks (react-aria), 'unstyled components' (react-aria-components), or 'styled components' (react-spectrum) for your project and use the appropriate package and documentation. Do not mix and match without understanding the implications.
• gotcha The peer dependencies for `react` and `react-dom` include a wide range of versions (e.g., `^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1`). While this offers flexibility, ensure your project's React version aligns with the tested ranges to avoid potential compatibility issues, especially with pre-release versions.
  Fix: Verify your `react` and `react-dom` versions in `package.json` are within the supported peer dependency range for the `react-aria` version you are using. Update React if necessary, or consider a different `react-aria` version if constraints are an issue.

Install

• npm install react-aria npm
• yarn add react-aria yarn
• pnpm add react-aria pnpm

Imports

• useButton
  wrong:

  const { useButton } = require('react-aria');

  correct:

  import { useButton } from 'react-aria';

  React Aria is an ESM-first library. CommonJS `require` is generally not recommended and might not work in all environments, especially with modern build tools. Ensure your project is configured for ESM.
• useFocusRing
  wrong:

  import useFocusRing from 'react-aria/useFocusRing';

  correct:

  import { useFocusRing } from 'react-aria';

  All hooks and utilities are typically imported directly from the 'react-aria' package. Direct deep imports from sub-paths are generally not supported or recommended and can lead to issues with tree-shaking or module resolution.
• mergeProps

  import { mergeProps } from 'react-aria';

  Used to safely merge props objects from multiple hooks or custom props without overwriting event handlers or attributes. Essential when combining multiple React Aria hooks or integrating with other libraries.

Quickstart

This quickstart demonstrates how to create a custom accessible button using `useButton` from React Aria, applying the necessary props and a ref to a native HTML button element. It also shows `mergeProps` for combining properties.

import React from 'react';
import { useButton } from 'react-aria';
import { mergeProps } from 'react-aria';

interface MyButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  onPress?: () => void;
}

function MyButton(props: MyButtonProps) {
  let ref = React.useRef<HTMLButtonElement>(null);
  let { buttonProps, isPressed } = useButton(props, ref);

  return (
    <button
      {...mergeProps(buttonProps, props)}
      ref={ref}
      style={{
        backgroundColor: isPressed ? 'darkblue' : 'blue',
        color: 'white',
        padding: '10px 20px',
        border: 'none',
        borderRadius: '5px',
        cursor: 'pointer'
      }}
    >
      {props.children}
    </button>
  );
}

// Example usage in a component
export function App() {
  const handlePress = () => {
    console.log('Button pressed!');
    alert('Hello from React Aria Button!');
  };

  return (
    <div>
      <h1>React Aria Quickstart</h1>
      <MyButton onPress={handlePress}>Click Me</MyButton>
    </div>
  );
}