Docs hard to comprehend

[Faithfinder]

Provide your feedback here.

We're currently trying to build Select/MultiSelect components (which I guess you would call "TagField", when it's finally it's turn to be implemented?). React-Aria seems like the best choice feature-wise, but comprehension has been a struggle. I think I grasped the part that at the core, I just need to manage and pass around a Collection and SelectionManager, however the details are elusive.

For example: ListBox is a critical part of any such component, and is mentioned in most of relevant docs. Moreover, it's mentioned with the idea that we can build it once and just reuse. However usage examples are different in different pages:

• Example in the useListBox itself puts useListState inside the ListBox component
• Example in the useSelect instead passes state from useSelectState as a prop
• We would like to allow booleans and null as possible values to be selected in the components. Seems like useListData is made for building a collection where keys need to be massaged a bit to be useable, however in that example ListBox accepts items and selectedKeys, not state.

Then, the docs menu is sorted... A bit weird? There's useSingleSelectListState at the top, but it's really just a building block for useSelectState that's at the bottom of the list?

I'm at a loss as to what pattern is suggested. Also, the types are all referencing each other. I've been staring at words List Select Props Options and State in, it seems, all possible combinations, for the last 3 days, and am feeling quite exhausted.

[reidbarber]

We definitely agree that combining the hooks can be cumbersome, and that is one of the reasons we created React Aria Components. We're hoping these unstyled components can be an easier way to get started, and they can choose to drop down to hooks if they need something more custom.

Then, the docs menu is sorted... A bit weird? There's useSingleSelectListState at the top, but it's really just a building block for useSelectState that's at the bottom of the list?

These are categorized, where the categorizes are sorted alphabetically, so there isn't necessarily a relationship between order and dependency in the menu.

I'm at a loss as to what pattern is suggested.

Beyond the examples in the docs, we recommend looking at the source code of individual React Spectrum components to get more ideas for implementation.

Hopefully that helps, and again, we're hoping that developer experience is improved by using the unstyled components as a starting point. Feel free to create a Discussion or Issue for specific ideas or recommendations.

[Faithfinder]

So, I've thought about possible solutions, and here are some, in no particular order:

1. There needs to be a "Reference implementation" of "common" components. E.g, when ListBox is referred from useSelect or useListData, it must be the same ListBox. It's simply confusing otherwise. It can either be the main "Example" on the component's (ListBox's) page, or a special section "Reference implementation" that will be linked to.
2. Explicit compatibility notes on hooks. Ideally, each hook would have sections for:
   • This hook accepts output from these other hooks as it's 1st argument (repeat for as many arguments as there are):
   • The props this hooks accepts are the same as these other hooks:
   • The output of this hook can be consumed by the following hooks:
   • The following hooks are built using this one, you probably don't need both at the same time:
3. Be better at linking: currently, useSelect page doesn't have a link to useSelectState, only definition popups.
4. Maybe a tag system for different kind of groupings? I'm really missing a way to see related elements of the system. I sort of get how the current categories came to be, but I wish for more.

[mryechkin]

Wholeheartedly agree with all the points you've brought up @Faithfinder 💯

I've implemented a Select component using useSelect hook and the provided examples - and while that was still a bit hard to grok, the Codesandbox examples helped a great deal.

I'm now looking to extend this component to support multiple selection, and I'm simply at a loss as to how to do it. There are no such examples in the docs, and mentions of multiple selection seem to be scattered across several doc pages. It's pretty confusing. Digging through source code of React Spectrum isn't exactly great DX - it would be super helpful to have more examples of these fairly common use cases.

[devongovett]

Multiple selection is not supported by Select, which is why you are not finding it. You could use ListBox with a popover to implement that though.

[mryechkin]

Ah, I see. Thanks for the clarification @devongovett. The State Management section in the useSelect docs makes it sound like it is.

[DoReVo]

I was also looking for a way to implement multiple selection with Select, and the documentation somewhat suggests that it's possible, especially since it lists the props for ListBox within the Select documentation. This is a bit confusing, I tried modifying the ListBox props to allow multiple selections, and it works, but only when it's not used inside a Select. Otherwise, the SelectionMode prop of ListBox seems to be ignored if it's used within a Select.

[vincerubinetti]

I was also looking for a way to implement multiple selection with Select, and the documentation somewhat suggests that it's possible, especially since it lists the props for ListBox within the Select documentation. This is a bit confusing, I tried modifying the ListBox props to allow multiple selections, and it works, but only when it's not used inside a Select. Otherwise, the SelectionMode prop of ListBox seems to be ignored if it's used within a Select.

Definitely agree with this. I guess this is a downside of the heavy use of composition in this library, or maybe just in the docs. If the ListBox selectionMode prop does nothing when inside a Select, I'd expect it to not be listed on the page as something you can change. There is a generic note above it that says "Within a <Select>, most <ListBox> props are set automatically", but that doesn't imply that you can't set them yourself.

Multiple selection is not supported by Select, which is why you are not finding it. You could use ListBox with a popover to implement that though.

Reading #2140, it seems like this may or may not come to the Select component. Until then, what would be a "recipe" for implementing it be?

<DialogTrigger>
  // "All Selected" | "None Selected" | "N Selected" | "Some option label" (if exactly 1 selected)
  <Button>2 items selected</Button>
  <Popover>
    <Dialog>
      <ListBox>
         <ListBoxItem />
      </ListBox>
    </Dialog>
  </Popover>
</DialogTrigger>

What about something like this? Where I don't need a type-able combobox or de-selectable tag pills, I just want a button trigger with a concatenated label and a popover.