Consider upgrading to a component-based API

[ianstormtaylor]

This library is awesome for the breath it provides for components and interactions and accessibility. Everything is clearly very well considered. And the goal of it being completely customizable is admirable and why I'd use it.

But as a user, the majority of my time using it is spent in very frustrating to debug "glue code" between the many hooks. It may not feel confusing as maintainers because you know the ins and outs of every hook, but let me tell you as a user, this is an extremely confusing library.

A big part of this is because of the decision to only provide hooks as the main API. The existing hooks are great for low-level use cases where some hyper-specific customization is required. But 90% of use cases don't need this.

I think this library would greatly benefit from taking an approach similar to Headless UI, which is based around components. With smart use of internal context to connect things together they are able to eliminate all of the tedious glue code, allowing you to focus purely on the components, state, and events. It's wonderfully simple to reason about. (And the existing hooks API could still be available for the 10% of cases that need extreme customization.)

---

For context, take a look at how implementing a Listbox differs between React ARIA's current API, and how HeadlessUI does it...

React ARIA

import React from "react";

import {
  useSelect,
  HiddenSelect,
  mergeProps,
  useFocusRing,
  useButton,
  useListBox,
  useOption,
  useOverlay,
  DismissButton,
  FocusScope
} from "react-aria";
import type { AriaListBoxOptions } from "@react-aria/listbox";
import type { AriaSelectProps } from "@react-types/select";
import type { Node } from "@react-types/shared";
import { ListState, Item, useSelectState } from "react-stately";

const animals = [
  { id: "red panda", name: "Red Panda" },
  { id: "cat", name: "Cat" },
  { id: "dog", name: "Dog" },
  { id: "aardvark", name: "Aardvark" },
  { id: "kangaroo", name: "Kangaroo" },
  { id: "snake", name: "Snake" }
];

export function ReactAria() {
  return (
    <Select label="Favorite Animal">
      {animals.map((animal) => (
        <Item key={animal.id}>{animal.name}</Item>
      ))}
    </Select>
  );
}

function Select<T extends object>(props: AriaSelectProps<T>) {
  let state = useSelectState(props);
  let ref = React.useRef(null);
  let { labelProps, triggerProps, valueProps, menuProps } = useSelect(
    props,
    state,
    ref
  );
  let { buttonProps } = useButton(triggerProps, ref);
  let { focusProps, isFocusVisible } = useFocusRing();
  return (
    <div className="inline-flex flex-col relative w-52 mt-4">
      <div
        {...labelProps}
        className="block text-sm font-medium text-gray-700 text-left cursor-default"
      >
        {props.label}
      </div>
      <HiddenSelect
        state={state}
        triggerRef={ref}
        label={props.label}
        name={props.name}
      />
      <button
        {...mergeProps(buttonProps, focusProps)}
        ref={ref}
        className={`p-1 pl-3 py-1 relative inline-flex flex-row items-center justify-between rounded-md overflow-hidden cursor-default shadow-sm border-2 outline-none ${
          isFocusVisible ? "border-pink-500" : "border-gray-300"
        } ${state.isOpen ? "bg-gray-100" : "bg-white"}`}
      >
        <span
          {...valueProps}
          className={`text-md ${
            state.selectedItem ? "text-gray-800" : "text-gray-500"
          }`}
        >
          {state.selectedItem
            ? state.selectedItem.rendered
            : "Select an option"}
        </span>
      </button>
      {state.isOpen && (
        <Popover isOpen={state.isOpen} onClose={state.close}>
          <ListBox {...menuProps} state={state} />
        </Popover>
      )}
    </div>
  );
}

function ListBox(
  props: {
    listBoxRef?: React.RefObject<HTMLUListElement>;
    state: ListState<unknown>;
  } & AriaListBoxOptions<unknown>
) {
  const ref = React.useRef<HTMLUListElement>(null);
  const { listBoxRef = ref, state } = props;
  const { listBoxProps } = useListBox(props, state, listBoxRef);
  return (
    <ul
      {...listBoxProps}
      ref={listBoxRef}
      className="max-h-72 overflow-auto outline-none"
    >
      {[...state.collection].map((item) => (
        <Option key={item.key} item={item} state={state} />
      ))}
    </ul>
  );
}

function Option(props: { item: Node<unknown>; state: ListState<unknown> }) {
  const { item, state } = props;
  const ref = React.useRef<HTMLLIElement>(null);
  const { optionProps, isDisabled, isSelected, isFocused } = useOption(
    { key: item.key },
    state,
    ref
  );

  let text = "text-gray-700";
  if (isFocused || isSelected) {
    text = "text-pink-600";
  } else if (isDisabled) {
    text = "text-gray-200";
  }

  return (
    <li
      {...optionProps}
      ref={ref}
      className={`
        m-1 rounded-md py-2 px-2 text-sm outline-none cursor-default flex items-center justify-between 
        ${text} 
        ${isFocused ? "bg-pink-100" : ""} 
        ${isSelected ? "font-bold" : ""}
      `}
    >
      {item.rendered}
    </li>
  );
}

function Popover(props: {
  popoverRef?: React.RefObject<HTMLDivElement>;
  children: React.ReactNode;
  isOpen?: boolean;
  onClose: () => void;
}) {
  const ref = React.useRef<HTMLDivElement>(null);
  const { popoverRef = ref, isOpen, onClose, children } = props;
  const { overlayProps } = useOverlay(
    {
      isOpen,
      onClose,
      shouldCloseOnBlur: true,
      isDismissable: false
    },
    popoverRef
  );
  return (
    <FocusScope restoreFocus>
      <div
        {...overlayProps}
        ref={popoverRef}
        className="absolute z-10 top-full w-full shadow-lg border border-gray-300 bg-white rounded-md mt-2"
      >
        {children}
        <DismissButton onDismiss={onClose} />
      </div>
    </FocusScope>
  );
}

HeadlessUI

import React, { useState } from "react";

import { Listbox } from "@headlessui/react";

const animals = [
  { id: "red panda", name: "Red Panda" },
  { id: "cat", name: "Cat" },
  { id: "dog", name: "Dog" },
  { id: "aardvark", name: "Aardvark" },
  { id: "kangaroo", name: "Kangaroo" },
  { id: "snake", name: "Snake" }
];

export function HeadlessUi() {
  const [selectedAnimal, setSelectedAnimal] = useState<
    typeof animals[number] | null
  >(null);
  return (
    <Listbox value={selectedAnimal} onChange={setSelectedAnimal}>
      <Listbox.Label className="block text-sm font-medium text-gray-700">
        Favorite Animal
      </Listbox.Label>
      <div className="mt-1 relative">
        <Listbox.Button className="bg-white relative w-full border border-gray-300 rounded-md shadow-sm pl-3 pr-10 py-2 text-left cursor-default focus:outline-none focus:ring-1 focus:ring-indigo-500 focus:border-indigo-500 sm:text-sm">
          {selectedAnimal?.name ?? "Choose…"}
        </Listbox.Button>
        <Listbox.Options className="absolute z-10 mt-1 w-full bg-white shadow-lg max-h-60 rounded-md py-1 text-base ring-1 ring-black ring-opacity-5 overflow-auto focus:outline-none sm:text-sm">
          {animals.map((animal) => (
            <Listbox.Option
              key={animal.id}
              value={animal}
              className={({ active }) =>
                `
                  cursor-default select-none relative py-2 pl-3 pr-9
                  ${active ? "text-white bg-indigo-600" : "text-gray-900"}
                `
              }
            >
              {({ selected, active }) => (
                <>
                  <span
                    className={`
                      block truncate
                      ${selected ? "font-semibold" : "font-normal"}
                    `}
                  >
                    {animal.name}
                  </span>
                </>
              )}
            </Listbox.Option>
          ))}
        </Listbox.Options>
      </div>
    </Listbox>
  );
}

The HeadlessUI code is much easier to reason about because all of the glue code is handled under the covers by the library using context. Whereas the React ARIA code is full of hooks and refs and state that needs to be connected together just right to get things to work.

---

Edit: Unfortunately I wasn't super clear, but I'm advocating for both hooks and components APIs. Obviously the hooks are low-level and useful for edge cases. But I think adding components alongside them would be nicer to use for 90% of cases.

[devongovett]

Hey, thanks for the feedback! React Aria is certainly low level. Our goal when releasing it was that it could accommodate the widest possible number of use cases. This includes the ability to fully customize the appearance, DOM structure, behavior, etc. We aim to let you have just as much control as if you were building the component from scratch with the raw DOM APIs as you might have before, but also provide a lot of behavior and a11y for you. Our hope was that higher level libraries like Headless UI would be built on top of React Aria. It's only possible to do this one way: the lower level hooks have to come first.

We did look at component and render-props based APIs when designing React Aria. In fact, we started thinking about this problem long before Hooks even existed. However, we never found the right way to do this that offered enough customization potential. Our goal was to build something that we could build React Spectrum (our design system) off of, and I don't think we could have done that without lower level access in some areas.

A few considerations:

• The components are mainly designed to be used as part of a larger design system. Headless UI is definitely simpler to use when you only use one component, but you may find yourself duplicating some things in a larger project. For example, in the React Aria code you showed above, the ListBox and Popover components can be reused for other things, like standalone lists, and menus. This can be hard for us to show on the documentation site for components that compose several pieces together like this, because you need all pieces first before you can put them together. Perhaps there's more we can do to improve this.
• Custom styling often requires extra DOM elements, or access to internal state. For example, a Tabs component with an animating line to indicate the selection requires an extra element and access to the DOM nodes for each tab to measure their sizes. Or perhaps you want to enable virtual scrolling for long lists, but still enable keyboard navigation even when all of the elements aren't rendered. Coupling components to a pre-defined DOM structure and relying on context definitely has limitations.
• Another goal is to share as much as possible across platforms. For example, the react-native-aria project is reusing our React Stately hooks to build equivalent versions for React Native. This type of sharing wouldn't have been possible with monolithic components.
• Customizing the behavior sometimes requires overriding properties returned by React Aria. For example, if you wanted to override some keyboard behavior for a specific case, you could override the onKeyDown prop returned from a hook and call it conditionally from within your own implementation. Doing this with a component API that renders the DOM elements for you would be tricky.
• There's a tradeoff between functionality and bundle size. Some components might have a lot of functionality that might not be useful across all products. For example, tables could have column resizing/reordering, drag and drop, multi-selection, etc. and not all of this may always be needed. We could include all of that in a single component with props to turn things on or off, but the tradeoff is that you're always paying the bundle size cost for code that's not actually used. Hooks provide a clean way to share small pieces of functionality that can be composed together within a single component, with the downside being, as you said, some glue code.

That being said, I do think there is a lot we can do to improve here without compromising on these goals. We've started at the lowest level layer possible, and are slowing working our way up the stack to provide higher level abstractions. Here are some ideas we have been thinking about:

• Combine some hooks that are very commonly used together. For example, buttons almost always need a focus style. We could combine the call to useFocusRing into useButton and return an isFocusVisible state so you don't need to do that yourself. useOverlay could have a focus scope built in for focus trapping. useSelect could potentially have useButton builtin, etc. The tradeoff is that if you're using the native :focus-visible, a different focus trapping library, or something else you get a bit of code you don't use, however, for some things this may be worth it. Figuring out where to draw that line is an interesting challenge.
• Expose more states from the hooks that could be used for styling. We've started doing this already – the isSelected/isFocused/etc. values returned from useOption were recently added. This avoids you needing to compute this yourself. We plan to continue adding more of these across the hooks.
• Reduce the amount of things you need to pass between hooks, e.g. between parents and children. We can often attach multiple things to the state object that you pass down rather than needing to pass a bunch of other options to child hooks.
• Create higher level hooks that combine more things together. This is related to the first one, but in some cases, rather than merging everything into one hook and causing larger bundles for everyone, we could keep the lower level hooks and also provide some higher level wrappers for common combinations.

Overall, the goal should be to reduce the number of different hooks you need to call for common cases, while retaining flexibility to drop down to lower level APIs where needed.

We don't currently have plans to offer an official component-based wrapper around our hooks, mainly for lack of time, but we would encourage and assist the community in such an effort. Personally, I would love to see multiple libraries with different takes on such an API built on top of React Aria, e.g. integrating with or optimizing for specific styling methodologies (e.g. tailwind, css-in-js, etc.). If you or anyone else is interested in working on such a library, we'd be happy to assist in any way we can. 😄

[ianstormtaylor]

Hey @devongovett, thanks for the thoughtful response!

I totally agree that hooks provide more control for certain edge cases where you need to get really custom (although some of those examples are solvable by components). I think hooks would still be key as the tiny building blocks, but an additional component-based layer would solve 90% of use cases without the current complexity.

It's hard to overstate how much simpler the Headless UI approach is. Even if this library is for UI kits, I'd be willing to bet that a lot of people come to it when first implementing a specific component that isn't well handled by browser defaults. (In my case this was trying to add an autocomplete component to a fairly simple UI kit.)

Totally makes sense if it's a lack of time concern though. Hopefully Headless UI adds more components over time and the mismatch in breadth will be reduced. I could definitely see a useful library that aimed to do what they're doing but with React ARIA under the hood—I'll hold out hope that it's React ARIA itself one day!

[sandren]

I think it's difficult to directly compare React Aria and Headless UI because to me it seems that they serve slightly different purposes (I personally use both). I would say that the purpose of React Aria—and @devongovett can correct me if I'm wrong—is to effectively create your own flavor of a Headless UI, either for your own internal design system or for an open source project built on top of it.

The components that you create with React Aria can have any API you want. So instead of building a one-off components with React Aria like in your example, you can create a general purpose one with a reusable API. That means you could technically take your Headless UI example and change the import from import { Listbox } from "@headlessui/react" to import { Listbox } from "./listbox-built-with-react-aria" and use them the exact same way, render props included if you are so inclined! 😀

So to me it's more about the level of control you have over the abstraction. Headless UI comes out of the box ready to go, but offers less customization. React Aria requires some assembly, but you can build any API you want.

[DaniGuardiola]

🙌 I'm glad this was raised, btw hi @ianstormtaylor, I'm currently building a text editor with Slate, great lib!

I've been thinking about this for a long time. In our org, we are using a combination of react-aria and Radix UI, and it's been on my mind to build a bunch of Radix-like primitives on top of react-aria / react-stately. I think that, while nothing beats hooks when it comes to extensibility and customization, they have achieved a really good balance between having a high-level and easy to use abstraction, and making it extensible. I see two interesting patterns for this:

• Their recently simplified component extension API: asChild prop for slottable components.
• Optionally controlled state, making it possible to have uncontrolled components that still work correctly.

I bet it wouldn't be too hard to build primitives with a similar approach, on top of react-aria and react-stately.

One point where Radix and react-aria diverge is that Radix is designed around native HTML components like <button>, while react-aria sometimes wraps these elements with custom APIs like the press events API. In fact, this has been a little troublesome for us when combining Radix and react-aria. I guess it'd be a challenge to make something that works well for both react-aria based components and native HTML ones.

Anyway, that's just my two cents. If I had more time I'd definitely try to start a project like this! :)

PD: besides this, I think the improvements @devongovett mentions are also pretty awesome, and as a user I can't wait for them to become a reality.

[DaniGuardiola]

PD: this thread by @diegohaz (reakit creator) seems relevant too: https://twitter.com/diegohaz/status/1229499924062048260

Seems like Reakit is the most similar to what a react-aria based component library would look like. It has low-level hooks and high-level components, and you can use whatever you want depending on your needs. It basically bridges the gap between the two worlds, and it's similar to how I'd envision this kind of lib.

Relevant Reakit docs: https://reakit.io/docs/composition/#props-hooks

[ianstormtaylor]

@sandren thanks for the response. I totally get that, I definitely appreciate the flexibility of the hooks from React ARIA, and I'm very glad this library exists. I know you could theoretically build all of Headless UI on top of React ARIA—I'm definitely not arguing for eliminating them.

My point is more that I'd bet the majority of users of this library don't require the granularity (and added complexity) that hooks provide. Just look at the difference in imports between the two examples:

// Headless UI
import { Listbox } from "@headlessui/react";

// React ARIA
import {
  useSelect,
  HiddenSelect,
  mergeProps,
  useFocusRing,
  useButton,
  useListBox,
  useOption,
  useOverlay,
  DismissButton,
  FocusScope
} from "react-aria";
import type { AriaListBoxOptions } from "@react-aria/listbox";
import type { AriaSelectProps } from "@react-types/select";
import type { Node } from "@react-types/shared";
import { ListState, Item, useSelectState } from "react-stately";

With the current state of things... if it's ever possible for me to avoid React ARIA's APIs when adding a new component to my UI kit I will do that. And only when a nicer component-based package doesn't exist will I use React ARIA's hooks.

So I opened this issue to bring this up, because I think the library would go from useful to amazing if it provided both hooks and components. (Imagine a @react-components or something to complement the existing packages.)

@DaniGuardiola thank you! That is awesome. Radix UI seems like exactly what I was looking for—similar to Headless UI but with a larger collection of components. The asChild pattern is very smart. And looks like it can replace the majority of my uses of React ARIA—the only big one that's missing for my use case is autocomplete/combobox.

[DaniGuardiola]

@ianstormtaylor

looks like it can replace the majority of my uses of React ARIA

Yep, we're using Radix everywhere it fits for its simplicity, and Aria in places where we need more customization or for things that Radix hasn't covered yet, like the awesome press interactions. I think it's possible to have the best of both worlds, although it doesn't come without complications when you have to combine the two 😆

Hit me up when you try and fail to use a react-aria based button as a Radix trigger, I'll help and save you a world of pain :)

[devongovett]

Hey all, thanks for your comments, this is a good discussion. I agree that having both higher level components and lower level hooks would be great. All of the libraries mentioned are good, but I think they are optimized for different use cases. As far as I can tell, all of them could be built on top of React Aria internally if their authors desired.

Here are some tradeoffs with various component-based APIs:

• Headless UI is clearly optimized for usage with Tailwind (makes sense). The className prop allows passing a function which receives an object containing various states like active, selected, etc. This can be used to generate classes on demand based on state, which is required for usage with Tailwind since it doesn't rely on custom CSS selectors. However, using Headless UI with another styling framework might be challenging because it doesn't expose states when you aren't using class names.
• Radix and Reakit (and also Reach UI) are optimized for use with plain CSS or CSS-in-JS. For styling, they expose states as attributes (e.g. data-state="active" or aria-selected="true") on their DOM elements, which can be styled using CSS selectors. This makes it difficult to use with something like Tailwind, where you aren't writing CSS selectors, and need to conditionally apply classes instead. Same would be true for some CSS-in-JS libraries that don't use CSS selectors. It's also challenging to use if the component doesn't expose whatever internal state you need as a data attribute.

These also tend to get complicated very quickly as soon as you want to do something even a little custom. Animated tabs is a good example. In order to do this, you need to take ownership of the state so you have access to the selection beyond just DOM attributes. Here's how Reach UI shows to do it: https://reach.tech/tabs/#animation. And here's an example using React Aria: https://codesandbox.io/s/practical-monad-punzo?file=/src/App.js. Because you already own the state, it's trivial to add a useEffect and an extra DOM element to render the selection.

I think it will be hard to design a single component-based API around React Aria that works for a wide number of use cases. That's why I hope the community will begin to explore different APIs for this that are optimized for specific use cases, e.g. react-aria-tailwind, react-aria-styled-components, etc. We would love to help wherever we can here! 😄

[devongovett]

I briefly prototyped an example of what this could look like using the Select component in your example above, but moving all of the styling to be passed in with an API similar to what Headless UI offers: https://codesandbox.io/s/intelligent-wright-7wi39?file=/src/App.js.

It uses functions passed to className for styling, which receive various states to apply conditional classes. It also uses render props to customize item elements and trigger contents. State is shared between all of the components via context, along with props returned from React Aria's useSelect hook.

This type of API does have a couple limitations though. Rather than passing <Item> elements as children, as React Aria currently expects, this type of API needs to allow passing any elements you want. Normally, React Aria uses the Item children to determine what items are in the collection. These are used to implement keyboard navigation, typeahead, etc. When there are arbitrary children, and the items could be at any nesting level, this is more challenging.

Headless UI and other libraries solve this using either a registration system using context, or by querying the DOM tree. Both of these require all of the items to be rendered to the DOM to work. You can't implement virtualized scrolling because keyboard navigation wouldn't be able to access items that are out of view and not rendered. That's why React Aria queries the JSX tree for Item elements instead, but it can't do this at arbitrary nesting.

For this demo, I instead relied on an items prop being an array of objects with a specific shape (id and name properties). This provides React Aria enough information to implement keyboard navigation, and we can pass those objects back to a render prop to render the actual Option elements. It's a little less ergonomic of an API than providing <Item> children, but it's the only other way to work with React Aria's existing hooks and support virtualized scrolling.

Anyway, hopefully this example shows that it's possible to build an API like Headless UI on top of React Aria, and what the implementation could look like. Anyone is welcome to use and extend this code. 😉

[ianstormtaylor]

@devongovett thanks for the follow ups!

Thing is though, those examples are sort of proving my point. The underlying logic in the <Select> example is very convoluted to follow. I can't imagine anyone (but a maintainer of React ARIA themself) writing that code without lots of time spent debugging things they hooked up incorrectly. And if you modified it to include TypeScript typings—like many would need—the confusion would increase another 2-3x.

It just reinforces my belief that React ARIA is great because it can do all these things, but I personally hope to touch it as little as possible, because its current abstractions just don't match what most people need. I'd feel irresponsible recommending people base a new UI Kit on it because of the complexity it would force on them, and instead I'd recommend it as a way to fill the gaps as a last resort.

[devongovett]

I really don't think it's that bad (seriously, look at the amount of functionality, flexibility, and reusability you get in ~100 lines), but I agree that we have some improvements to make. Again, React Aria is designed for developers who are building component libraries, not one-off components in apps. The example is mainly using React features like context which I would hope most developers are familiar with if they're building a component library. And once we implement the changes I mentioned previously so you only need to call ~1 hook per component, it will be much better. I do think more design systems need the flexibility React Aria offers than you're giving credit for, but I hope to see libraries built around React Aria for simple use cases too.

[tk-bitio]

I think I agree with @ianstormtaylor. I've been using react-aria for a month daily, and I am still nowhere near being able to make that example by myself. I can barely understand as it is, and cannot use in ways that are too different from the examples given in the docs. It could totally be that I'm just an amateur developer, but I don't even feel like I'm getting better or understanding what the hooks are really doing.

Better documentation here would be really helpful here for me (higher level guides explaining how focus or keyboard navigation works), or higher level hooks, or less confusing typings.

[devongovett]

We do have some higher level guides already covering some of these topics:

• Accessibility
• Interactions (including keyboard and focus)
• Internationalization

What additional details do you think are missing here that would be helpful?

I'm also curious if you find the way the useTable docs are written to be easier to follow? They are written more as a tutorial given there are lots of different pieces.

And again, I'm definitely not disagreeing that we can make lots of improvements to make React Aria easier to use, and also that a higher level component-based wrapper would be a useful project. I'm just not convinced that using a component-based API is the only way.

[ianstormtaylor]

@tk-bitio I've been using react-aria for a month daily, and I am still nowhere near being able to make that example by myself. I can barely understand as it is, and cannot use in ways that are too different from the examples given in the docs. It could totally be that I'm just an amateur developer, but I don't even feel like I'm getting better or understanding what the hooks are really doing.

It's not your fault, I feel the same way, and I'd consider myself a fairly advanced JS/TS/React user. It's due to the way React ARIA is designed, as a collection of hooks that have to be connected in just the right way for it to work at all.

@devongovett I really don't think it's that bad (seriously, look at the amount of functionality, flexibility, and reusability you get in ~100 lines), but I agree that we have some improvements to make.

I agree that the functionality is great. What the library is capable of is great.

But the idea that because it's only ~100 LOC means it's the best abstraction for the job isn't right. Those ~100 LOC are full of very complex and brittle connections that are very easy to hook up incorrectly. And it's very easy to omit things that either (a) break your component noticeably, or (b) break the accessibility of your components without you knowing. (And that's assuming you're able to glue it all together in a workable way at all.)

Most people would be much better served by the ever-so-slightly-less-flexible components that Headless UI or Radix UI provide, due to the much simpler usage and better guarantees that your components end up being as accessible as you think.

@devongovett Again, React Aria is designed for developers who are building component libraries, not one-off components in apps. The example is mainly using React features like context which I would hope most developers are familiar with if they're building a component library.

Yeah, that's what I'm using it for.

I'm very comfortable with React context—that has nothing to do with why using React ARIA is complex.

I'm not a BigCo though, so I'm using it to make a <Select> component that I can then re-use throughout my app—not packaging it up for other teams to use. But making that re-usable <Select> in the first place is very hard. Like @tk-bitio said, you have to copy examples currently to get anything usable—writing anything from scratch requires too much library-specific knowledge to be possible.

It's a design/architecture issue. React ARIA gives you the tools to make it technically possible to build all of these nice, accessible UI components. But it doesn't actually make building them simple (or easy). And it doesn't help guarantee that you hook them up in a way that makes them accessible either.

[stefanprobst]

you have to copy examples currently to get anything usable

don't the copypastable examples in the docs solve 90% of usecases?

[tanishqkancharla]

(im tk-bitio, this is my personal acc.)

don't the copypastable examples in the docs solve 90% of usecases?

That’s not the way I want to be using a library. If Im using react ARIA, I want to use build my own accessible interactions. Those 90% of use cases are exactly the use cases covered by other libraries like Headless and Radix. Ive been working on a Tab component for a day and I cant get tab navigation to work. I have no idea whats going wrong, and no good way to debug except understanding what every hook is doing in detail.

@devongovett, those articles are great, but don’t provide examples/explanations of implementations from react aria. I dont mean full built out code examples, just an example of the relevant hooks and how to compose them.

The useTable docs are great! I havent used it, but I can already see there’s a lot more explanation of whats going on, and what the particular hooks are doing.

I think the low level hooks are important. Ive already needed to build my own interactions that are different from examples. At the same time, the overhead needed for commonplace interactions feels like too much. Higher level hooks or components that just act as compositions for the current ones seems like a good idea to me bc they serve the dual purpose of fulfilling a swath of usecases and acting as guides on the correct way to compose the low level hooks (letting you modify it as needed)

Btw, while I’m here: I’m really thankful for the hard work the react spectrum team is doing. I’m glad this exists, helping devs build more accessible interfaces easier. I think thats the general goal of this library and that makes this a productive discussion.

Also, is the docs website open source? I cant seem to find it

[devongovett]

Can you explain what you find complicated? I don't think I understand what you're complaining about in particular. If you look at the examples that already do what I was describing we want to do more of, it's a single function call per component, and you spread the returned props onto your DOM elements. What do you find complex about this?

Those ~100 LOC are full of very complex and brittle connections that are very easy to hook up incorrectly.

What do you think is complex or brittle there? Could you give me some specific examples?

And it's very easy to omit things that either (a) break your component noticeably, or (b) break the accessibility of your components without you knowing.

Like what? Assuming we combined some of the hooks that need to be chained together manually right now so it was usually one hook call per component, would you still have the same concerns?

Perhaps we are thinking about this differently. I think of it as if you were going to write the component yourself from scratch with only the DOM. In that case, you would write your code in almost the exact same way with and without React Aria, you just wouldn't have to implement a bunch of the behavior yourself.

Personally, I find the HeadlessUI and Radix approach much more difficult to understand because it's hard to see what they are rendering under the hood without reading their source code. How do I know what type of element they are rendering? Are they rendering one element or more than one? If more than one, how do I customize the outer ones vs inner ones? How do I customize the styles based on state? Each library has a different way of doing that. How do I get access to a ref to an inner element (e.g. for measuring something)? It may look like less code, but I find it much harder to reason about, especially when you want to do any kind of customization (the whole point of all of these libraries!). With React Aria, you are doing all of the rendering yourself so you can easily see how everything works, and it's trivial to customize things just like you're used to with any DOM-based component you'd write from scratch.

[devongovett]

@moonrise-tk Tabs is a good example. It's already one hook call per component for the most part: https://react-spectrum.adobe.com/react-aria/useTabList.html#example. The changes based on the above ideas would likely be to compute isSelected and isDisabled for you and return those from useTab so you don't need to compute them from state yourself. Could you explain more what you were having issues with?

those articles are great, but don’t provide examples/explanations of implementations from react aria. I dont mean full built out code examples, just an example of the relevant hooks and how to compose them.

I will need to think about this more. A lot of this is covered in the examples for individual components, but I agree we need to add more explanations about it similar to the table docs.

Also, is the docs website open source?

Yes, the docs for each component are found within each package, e.g. packages/@react-aria/tabs/docs.

[ianstormtaylor]

@devongovett Can you explain what you find complicated? I don't think I understand what you're complaining about in particular. If you look at the examples that already do what I was describing we want to do more of, it's a single function call per component, and you spread the returned props onto your DOM elements. What do you find complex about this?

What do you think is complex or brittle there? Could you give me some specific examples?

The complexities are scattered all over the codebase and docs. Lots of little (and some bigger) things that add up to an overall picture of confusion and frustration when trying to use the library. Here are some...

• Despite components re-using pieces between them (eg. select, listbox, button), all of them are imported from different imports, so you end up having to add 5-10 dependencies to your app just to get a simple <Select> working. The basic useSlider example requires 6 different packages—it's impossible to write this without copy-pasting from the docs. (There are also the react-aria type packages, but they aren't used much in the docs, just in some examples, and they're still are many of them to import, so it just adds to the confusion.)

• The React ARIA hooks almost all require a state object passed as their second argument, and yet creating those state objects means importing a separate package, looking up a separate docs page, and calling yet another hook.

• The props that need to be passed into React ARIA hooks are often non-obvious. For example the useTab hooks requires passing in { key: item.key } as props. This isn't something you can "know" without copying an example directly from the docs. (And not only that, but even once you know it it's confusing because you'll also be doing <Item key={item.key} ... /> as well a few lines away.)

• Because the hooks are called in different places, you find yourself having to pass the same arguments in multiple times across different hooks to make them aware of what's going on (eg. orientation passed to slider-related hooks.).

• Because of the collections architecture instead of doing something like <Tabs><Tab>...</Tab></Tabs> when you use a components, you end up having to import a non-obvious React Stately <Item> component to use instead.

• Because of the prop-spreading API, it's very easy to accidentally forget to spread the props on to specific components like labels, buttons, etc. And then you'll be breaking accessibility without realizing it. The only safe-feeling way to get around this is to rely on copy-pasting examples from the docs.

• Naming isn't consistent between props passed to hooks and their types. For example in useSelect, there is a triggerProps argument which is of type AriaButtonProps (why not just call it buttonProps?). And there's a menuProps argument of type AriaListBoxOptions<unknown> (why not call it listBoxProps?). And then you go over to useCombobox and the props are named differently, and more like what you'd expect.

• Examining the props passed into a hook is tedious because they're listed in a popover. If you expand them and then scroll the page the popover closes (likely a bug). But even when you get passed that, the huge list of props is hard to read in the small space provider by a popover.

• There's no mention anywhere of what the the correct import is for types like AriaButtonProps.

• Users think in terms of the component they are implement (eg. <Select />), but the documentation is organized by groupings of hook in non-obvious ways. Such that implement a select component requires looking at 10+ pages in the docs (which are all in many different places in the sidebar, or even separate minisites) and switching between them constantly to make sure you've done everything right.

• The snippets in the docs don't actually list the imports for React ARIA components. (They're only listed once at the top of the page.) So you end up having to scroll back up often to remember which thing to import and where it comes from.

• The API heading in the docs and the prop descriptions under Anatomy are for some reason separated even though they are describing very similar things? And so you're scrolling between them to get the full API of a hook.

• Navigating between the "microsites" (ARIA vs. Stately) in the docs is also tedious, which is frustrating because you have to do it constantly to refer to the pieces that are spread across the different packages.

Uncovering this kind of thing yourself requires putting yourself in the shoes of a user, which can be hard.

If you compare all of this to the developer experience you get from Headless UI or Radix UI it's not even a competition. They're usually single-import and single documentation page. Their APIs are much closer to how you'd use DOM components so they're easy to make expectations about. They bake their state in with context so you don't have to repeat yourself. And the accessibility is baked in a layer underneath where you're working so you're guaranteed to get it right.

And because of all that, as currently architected the majority of use cases are better served by Headless UI or Radix UI.

[devongovett]

Thanks so much for taking the time to write those down! I think we can improve on most of them even without completely changing the API. And we'll continue thinking about how to provide a higher level API in some areas as well.

[ianstormtaylor]

Sounds great, looking forward to what you come up with!

[tk-bitio]

I agree with all of ianstormtaylor's points. It seems to me that this is more of a clarity/docs/organization-of-resources problem rather than an intrinsic problem with the hooks API. It can be solved by either exposing higher-level components like ian has suggested, or reworking the docs to make understanding the hooks easier. I personally prefer both :) so that I can rely on high-level components/hooks and then "drop down" to the low-level hooks if I need to build my own interactions.

I would love to work on/build a style-less library like Radix or Headless on React aria, but like I said, I still feel very lost. Maybe with a combination of improving the docs experience, and as I get more familiar with the library, this will be possible!

[devongovett]

Hey all! 👋

I've been thinking about how we can improve the DX of React Aria recently, and wanted to get your feedback. We're working on this on a number of fronts, but one of the major ones is potentially introducing a higher level component-based API built on top of the hooks that will be easier to get started with, but allows you to drop down to lower level APIs when you need to customize.

I've been prototyping what this API could look like in this repo: https://github.com/devongovett/react-aria-components (see App.js for an example). Here are the main ideas:

• It is a thin wrapper around the existing hooks. Most components (including all parts) are < 100 lines. This also makes it a good example if you need to copy/paste and modify for some reason.
• Generally a 1:1 mapping between components and DOM nodes, so you can style everything easily.
• Render props for children, className, and style props, which provide you a bunch of states for use in styling or custom rendering. I really like how Headless UI does this.
• Everything is built with composition. For example, rather than having both a Select.ListBox and ComboBox.ListBox component, there'd be a single ListBox component that is used by both Select and ComboBox. This allows you to reuse the same styles easily if you want, along with other benefits (below).
• Each component would also expose a context object, e.g. ListBoxContext, which would allow a parent component to send it props. This is what would allow the above composition to work. However, this also means you can write your own version of ListBox that consumes these props using the hook API, which would allow you more customization options, e.g. for example using virtualized scrolling, changing the DOM structure, access to internal state, etc. But rather than rewriting the whole ComboBox component when you need to do that, you'd be able to only swap out the ListBox. This also works the other way – you could replace the ComboBox but reuse the child ListBox by using the same context provider we do.
• We can probably be slightly more opinionated than other component libraries in terms of DOM structure, in favor of API simplicity and ensuring semantic markup. We would of course try to keep a 1:1 mapping between DOM nodes and components for easy styling, but sometimes this isn't possible or very ergonomic just due to ARIA pattern limitations. Rather than stretching this too far and making the API more complex than it needs to be, we can simply allow you to easily drop down to hooks when you need more control.
• All in a single package, so there's just one dependency for all components (tree shakeable of course).

I would really appreciate any feedback at all on the ideas above and the API. It's still very early and a work in progress. The main hurdle is figuring out how to document all of this in addition to our existing hook API in a coherent way that isn't overwhelming. We want to make it easier to get started, while allowing you to go deeper into the internals when you need more control.

So, is this something you would use? What do you think of the API? Any ideas on how you'd structure the documentation? Any and all suggestions/feedback welcome!

[devongovett]

Wanted to provide an update here. I've been slowly working on writing the docs, and iterating more on the API for styling, collections, etc.

The latest version of the docs are now here (click on other components in the left sidebar too). I would love to hear any feedback on the documentation structure, styling options, or anything else you might have thoughts about!

It's getting close to being ready to actually publish to npm, so I'll also let this thread know once that happens and you can try an early version yourself. Thanks again for the early feedback!

[tanishqkancharla]

A search bar would be awesome and helpful! But otherwise looks clean, and the component pages are awesome. The "View Repo" links are broken, but maybe those are private right now.

Thank you so much for this! Also if your team ever has the bandwidth, please consider writing some more blog posts about accessiblity and the hairy problems you guys have had to deal with. It's super interesting, and I would love to get more knowledgable about accessibility!

[devongovett]

Yeah it's not merged into the main branch yet which is why the repo links are broken for now (you can find the code here). Search is coming across the whole website (#3383), right now this is just focused on the component pages themselves. And yep, more blog posts are always coming - though they take a long time to write. 😄

[jamesopstad]

Amazing work, @devongovett. I think that having access to both the high-level components and low-level hooks is the best of both worlds. The component code also serves as a great reference for building custom implementations. Are you able to give any estimate for when the components will be released?

[devongovett]

Finally making progress on this again. I have written up an RFC with a detailed proposal for this feature. The PR also has links to the current implementation and docs. We would appreciate any and all feedback! #4058

[FranCarstens]

It's great to see this discussion happening. Like many developers I'm also stuck between the low-level implementation of Aria and the prescriptive design of Spectrum. My kingdom for something inbetween - fully functional, accessible, and headless components that allow me to pass style and className to implement my own design decisions.

[lou-daiglecostello]

Is there somewhere I can be looking to gauge a rough timeline for this work? This is maybe a question for @devongovett who might best understand the scope of work remaining on the new component-based API.

I am absolutely pumped about the speedy progress made on this initiative so far, having seen several PRs get merged already, just as my org is setting out to leverage react-aria in a new component library. I am eager to start trialing the component API instead, though, as soon as possible. We could roll with a pre-release version for now as long as docs are accessible.

[devongovett]

Our goal is to release the first alpha in the next few weeks.

[devongovett]

Hey all, we just shipped the first alpha of React Aria Components! We'd love to hear your feedback. Check out the docs here: https://react-spectrum.adobe.com/react-aria/react-aria-components.html

[FranCarstens]

This is awesome!

[tanishqkancharla]

Thanks for the super hard work, I know the Spectrum team put a lot of work into this. I will definitely be trying out the individual components! I love how long and detailed the documentation is.

I remember from somewhere that you guys were considering doing some advanced context-based, recursing-the-react-tree-yourself kind of stuff. Are there any gotchas there that people have to worry about? Maybe it's just me but I would love a page describing some of the intricate details of the implementation so that for debugging, I can have the right sort of mental model.

I think the react-aria documentation has gotten pretty long; a search bar in the sidebar would be really nice. Also, the hooks documentation pages could also be under their own top-level toggle.

[devongovett]

Yep search is in progress over in #3383, should be up very soon. The sidebar and homepage will get restructured more once the components are out of pre-release. We'll also have some more high level conceptual pages, but those still need to be written.

[devongovett]

Search is now live.

[devongovett]

React Aria Components v1.0.0 has now shipped, so I think we can finally close this out! Thanks @ianstormtaylor for raising this originally, and everyone for contributing your thoughts and ideas. ❤️ Check out our new landing page for all the details on the new API: https://react-spectrum.adobe.com/react-aria/index.html