packages/react-aria/docs/select/useSelect.mdx
{/* Copyright 2020 Adobe. All rights reserved. This file is licensed to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */}
import {Layout} from '@react-spectrum/docs'; export default Layout;
import docs from 'docs:@react-aria/select'; import collectionsDocs from 'docs:@react-types/shared/src/collections.d.ts'; import selectionDocs from 'docs:@react-stately/selection'; import statelyDocs from 'docs:@react-stately/select'; import overlaysDocs from 'docs:@react-aria/overlays'; import focusDocs from 'docs:@react-aria/focus'; import listboxDocs from 'docs:@react-aria/listbox'; import {HeaderInfo, FunctionAPI, TypeContext, InterfaceType, TypeLink, PageDescription} from '@react-spectrum/docs'; import packageData from '@react-aria/select/package.json'; import Anatomy from './anatomy.svg'; import ChevronRight from '@spectrum-icons/workflow/ChevronRight'; import {ExampleCard} from '@react-spectrum/docs/src/ExampleCard'; import examplePreview from 'url:./example.png'; import styledExamplePreview from 'url:./styled-components.png'; import popupExamplePreview from 'url:./popup-example.png';
<PageDescription>{docs.exports.useSelect.description}</PageDescription>
<HeaderInfo packageData={packageData} componentNames={['useSelect']} sourceData={[ {type: 'W3C', url: 'https://www.w3.org/WAI/ARIA/apg/patterns/listbox/'} ]} />
A select can be built using the <select>
and <option> HTML elements, but this is
not possible to style consistently cross browser, especially the options. useSelect helps achieve accessible
select components that can be styled as needed without compromising on high quality interactions.
listbox popup using ARIA (combined with useListBox)<select> elementA select consists of a label, a button which displays a selected value, and a listbox, displayed in a
popup. Users can click, touch, or use the keyboard on the button to open the listbox popup. useSelect
handles exposing the correct ARIA attributes for accessibility and handles the interactions for the
select in its collapsed state. It should be combined with useListBox, which handles
the implementation of the popup listbox.
useSelect also supports optional description and error message elements, which can be used
to provide more context about the field, and any validation messages. These are linked with the
input via the aria-describedby attribute.
useSelect returns props that you should spread onto the appropriate element:
<TypeContext.Provider value={docs.links}> <InterfaceType properties={docs.links[docs.exports.useSelect.return.base?.id ?? docs.exports.useSelect.return.id].properties} /> </TypeContext.Provider>
State is managed by the <TypeLink links={statelyDocs.links} type={statelyDocs.exports.useSelectState} />
hook from @react-stately/select. The state object should be passed as an option to useSelect
If a select does not have a visible label, an aria-label or aria-labelledby
prop must be passed instead to identify it to assistive technology.
useSelect requires knowledge of the options in the select in order to handle keyboard
navigation and other interactions. It does this using the <TypeLink links={collectionsDocs.links} type={collectionsDocs.exports.Collection} />
interface, which is a generic interface to access sequential unique keyed data. You can
implement this interface yourself, e.g. by using a prop to pass a list of item objects,
but <TypeLink links={statelyDocs.links} type={statelyDocs.exports.useSelectState} /> from
@react-stately/select implements a JSX based interface for building collections instead.
See Collection Components for more information.
In addition, <TypeLink links={statelyDocs.links} type={statelyDocs.exports.useSelectState} /> manages the state necessary for multiple selection and exposes a <TypeLink links={selectionDocs.links} type={selectionDocs.exports.SelectionManager} />, which makes use of the collection to provide an interface to update the selection state. It also holds state to track if the popup is open. For more information about selection, see Selection.
This example uses a <button> element for the trigger, with a <span> inside to hold the value,
and another for the dropdown arrow icon (hidden from screen readers with aria-hidden).
A <<TypeLink links={docs.links} type={docs.exports.HiddenSelect} />> is used to render a hidden native
<select>, which enables browser form autofill support.
The same Popover, ListBox, and Button components created with usePopover, useListBox,
and useButton that you may already have in your component library or application should be reused. These can be shared with other
components such as a ComboBox created with useComboBox or a Dialog popover created with useDialog.
The code for these components is also included below in the collapsed sections.
In addition, see useListBox for examples of sections (option groups), and more complex options. For an example of the description and error message elements, see useTextField.
import {HiddenSelect, useSelect} from '@react-aria/select';
import {Item} from '@react-stately/collections';
import {useSelectState} from '@react-stately/select';
// Reuse the ListBox, Popover, and Button from your component library. See below for details.
import {ListBox, Popover, Button} from 'your-component-library';
function Select(props) {
// Create state based on the incoming props
let state = useSelectState(props);
// Get props for child elements from useSelect
let ref = React.useRef(null);
let {
labelProps,
triggerProps,
valueProps,
menuProps,
hiddenSelectProps
} = useSelect(props, state, ref);
return (
<div style={{display: 'inline-block'}}>
<div {...labelProps}>{props.label}</div>
<HiddenSelect {...hiddenSelectProps} />
<Button
{...triggerProps}
buttonRef={ref}
style={{height: 30, fontSize: 14}}>
<span {...valueProps}>
{state.selectedItem
? state.selectedItem.rendered
: 'Select an option'
}
</span>
<span
aria-hidden="true"
style={{paddingLeft: 5}}>
▼
</span>
</Button>
{state.isOpen &&
<Popover state={state} triggerRef={ref} placement="bottom start">
<ListBox
{...menuProps}
state={state} />
</Popover>
}
</div>
);
}
<Select label="Favorite Color">
<Item>Red</Item>
<Item>Orange</Item>
<Item>Yellow</Item>
<Item>Green</Item>
<Item>Blue</Item>
<Item>Purple</Item>
<Item>Black</Item>
<Item>White</Item>
<Item>Lime</Item>
<Item>Fushsia</Item>
</Select>
The Popover component is used to contain the popup listbox for the Select.
It can be shared between many other components, including ComboBox,
Menu, and others.
See usePopover for more examples of popovers.
import type {AriaPopoverProps} from 'react-aria';
import type {OverlayTriggerState} from 'react-stately';
import {usePopover, Overlay, DismissButton} from '@react-aria/overlays';
interface PopoverProps extends Omit<AriaPopoverProps, 'popoverRef'> {
children: React.ReactNode,
state: OverlayTriggerState
}
function Popover({children, state, ...props}: PopoverProps) {
let popoverRef = React.useRef(null);
let {popoverProps, underlayProps} = usePopover({
...props,
popoverRef
}, state);
return (
<Overlay>
<div {...underlayProps} style={{position: 'fixed', inset: 0}} />
<div
{...popoverProps}
ref={popoverRef}
style={{
...popoverProps.style,
background: 'var(--page-background)',
border: '1px solid gray'
}}>
<DismissButton onDismiss={state.close} />
{children}
<DismissButton onDismiss={state.close} />
</div>
</Overlay>
);
}
The ListBox and Option components are used to show the list of options.
They can also be shared with other components like a ComboBox. See
useListBox for more examples, including sections and more complex items.
import {useListBox, useOption} from '@react-aria/listbox';
function ListBox(props) {
let ref = React.useRef(null);
let {listBoxRef = ref, state} = props;
let {listBoxProps} = useListBox(props, state, listBoxRef);
return (
<ul
{...listBoxProps}
ref={listBoxRef}
style={{
margin: 0,
padding: 0,
listStyle: "none",
maxHeight: 150,
overflow: "auto",
minWidth: 100,
background: 'lightgray'
}}>
{[...state.collection].map(item => (
<Option
key={item.key}
item={item}
state={state} />
))}
</ul>
);
}
function Option({item, state}) {
let ref = React.useRef(null);
let {optionProps, isSelected, isFocused, isDisabled} = useOption({key: item.key}, state, ref);
return (
<li
{...optionProps}
ref={ref}
style={{
background: isFocused ? 'gray' : 'transparent',
color: isDisabled ? 'gray' : isFocused ? 'white' : 'black',
padding: '2px 5px',
outline: 'none',
cursor: 'pointer',
display: 'flex',
justifyContent: 'space-between',
gap: '10px'
}}>
{item.rendered}
{isSelected ? <span>✓</span> : null}
</li>
);
}
The Button component is used in the above example to toggle the listbox popup. It is built using the useButton hook, and can be shared with many other components.
import {useButton} from '@react-aria/button';
function Button(props) {
let ref = props.buttonRef;
let {buttonProps} = useButton(props, ref);
return <button {...buttonProps} ref={ref} style={props.style}>{props.children}</button>;
}
<ExampleCard url="https://codesandbox.io/s/hardcore-moon-xzc4r?file=/src/ComboBox.tsx" preview={examplePreview} title="Tailwind CSS" description="An example of styling a Select with Tailwind." />
<ExampleCard url="https://codesandbox.io/s/sharp-sun-e3fgd?file=/src/Select.tsx" preview={styledExamplePreview} title="Styled Components" description="A Select with complex item content built with Styled Components." />
<ExampleCard url="https://codesandbox.io/s/heuristic-margulis-uz3d4d?file=/src/Select.tsx" preview={popupExamplePreview} title="Popup positioning" description="A Select with custom macOS-style popup positioning." />
The following examples show how to use the Select component created in the above example.
Select follows the Collection Components API, accepting both static and dynamic collections.
The examples above show static collections, which can be used when the full list of options is known ahead of time. Dynamic collections,
as shown below, can be used when the options come from an external data source such as an API call, or update over time.
As seen below, an iterable list of options is passed to the Select using the items prop. Each item accepts a key prop, which
is passed to the onSelectionChange handler to identify the selected item. Alternatively, if the item objects contain an id property,
as shown in the example below, then this is used automatically and a key prop is not required.
function Example() {
let options = [
{id: 1, name: 'Aerospace'},
{id: 2, name: 'Mechanical'},
{id: 3, name: 'Civil'},
{id: 4, name: 'Biomedical'},
{id: 5, name: 'Nuclear'},
{id: 6, name: 'Industrial'},
{id: 7, name: 'Chemical'},
{id: 8, name: 'Agricultural'},
{id: 9, name: 'Electrical'}
];
return (
<>
<Select label="Pick an engineering major" items={options}>
{(item) => <Item>{item.name}</Item>}
</Select>
</>
);
}
Setting a selected option can be done by using the defaultSelectedKey or selectedKey prop. The selected key corresponds to the key of an item.
When Select is used with a dynamic collection as described above, the key of each item is derived from the data.
See the react-stately Selection docs for more details.
function Example() {
let options = [
{name: 'Koala'},
{name: 'Kangaroo'},
{name: 'Platypus'},
{name: 'Bald Eagle'},
{name: 'Bison'},
{name: 'Skunk'}
];
let [animal, setAnimal] = React.useState("Bison");
return (
<Select
label="Pick an animal (controlled)"
items={options}
selectedKey={animal}
onSelectionChange={selected => setAnimal(selected)}>
{item => <Item key={item.name}>{item.name}</Item>}
</Select>
);
}
This example uses the useAsyncList hook to handle asynchronous loading of data from a server. You may additionally want to display a spinner to indicate the loading state to the user, or support features like infinite scroll to load more data.
import {useAsyncList} from '@react-stately/data';
function AsyncLoadingExample() {
let list = useAsyncList({
async load({signal, filterText}) {
let res = await fetch(
`https://pokeapi.co/api/v2/pokemon`,
{signal}
);
let json = await res.json();
return {
items: json.results
};
}
});
return (
<Select label="Pick a Pokemon" items={list.items} selectionMode="single">
{(item) => <Item key={item.name}>{item.name}</Item>}
</Select>
);
}
A Select can be fully disabled using the isDisabled prop.
<Select label="Choose frequency" isDisabled>
<Item key="rarely">Rarely</Item>
<Item key="sometimes">Sometimes</Item>
<Item key="always">Always</Item>
</Select>
useSelect supports marking items as disabled using the disabledKeys prop. Each key in this list
corresponds with the key prop passed to the Item component, or automatically derived from the values passed
to the items prop. See Collections for more details.
Disabled items are not focusable, selectable, or keyboard navigable. The isDisabled property returned by
useOption can be used to style the item appropriately.
<Select label="Favorite Animal" disabledKeys={['cat', 'kangaroo']}>
<Item key="red panda">Red Panda</Item>
<Item key="cat">Cat</Item>
<Item key="dog">Dog</Item>
<Item key="aardvark">Aardvark</Item>
<Item key="kangaroo">Kangaroo</Item>
<Item key="snake">Snake</Item>
</Select>
The open state of the select can be controlled via the defaultOpen and isOpen props
function Example() {
let [open, setOpen] = React.useState(false);
return (
<>
<p>Select is {open ? 'open' : 'closed'}</p>
<Select label="Choose frequency" isOpen={open} onOpenChange={setOpen}>
<Item key="rarely">Rarely</Item>
<Item key="sometimes">Sometimes</Item>
<Item key="always">Always</Item>
</Select>
</>
);
}
By default, interacting with an item in a Select triggers onSelectionChange. Alternatively, items may be links to another page or website. This can be achieved by passing the href prop to the <Item> component. Link items in a Select are not selectable. See the links section in the useListBox docs for details on how to support this.
useSelect and useListBox handle some aspects of internationalization automatically.
For example, type to select is implemented with an
Intl.Collator
for internationalized string matching. You are responsible for localizing all labels and option
content that is passed into the select.
In right-to-left languages, the select should be mirrored. The arrow should be on the left, and the selected value should be on the right. In addition, the content of list options should flip. Ensure that your CSS accounts for this.