Picker

Pickers allow users to choose a single option from a collapsible list of options when space is limited.

Ice cream flavor

size

labelPosition

labelAlign

necessityIndicator

isRequired

isQuiet

isDisabled

isInvalid

import {Picker, PickerItem} from '@react-spectrum/s2';

<Picker label="Ice cream flavor">
  <PickerItem>Chocolate</PickerItem>
  <PickerItem>Mint</PickerItem>
  <PickerItem>Strawberry</PickerItem>
  <PickerItem>Vanilla</PickerItem>
  <PickerItem>Chocolate Chip Cookie Dough</PickerItem>
</Picker>

Content

Picker follows the Collection Components API. It supports features such as static and dynamic collections, sections, disabled items, links, text slots, asynchronous loading, etc. See the Collections docs for more details.

The following example shows a dynamic collection of items, grouped into sections.

Preferred fruit or vegetable

import {Picker, PickerItem, PickerSection, Header, Heading, Text, Collection} from '@react-spectrum/s2';

function Example() {
  let options = [
    {name: 'Fruit', children: [
      {name: 'Apple'},
      {name: 'Banana'},
      {name: 'Orange'},
      {name: 'Honeydew'},
      {name: 'Grapes'},
      {name: 'Watermelon'},
      {name: 'Cantaloupe'},
      {name: 'Pear'}
    ]},
    {name: 'Vegetable', children: [
      {name: 'Cabbage'},
      {name: 'Broccoli'},
      {name: 'Carrots'},
      {name: 'Lettuce'},
      {name: 'Spinach'},
      {name: 'Bok Choy'},
      {name: 'Cauliflower'},
      {name: 'Potatoes'}
    ]}
  ];

  return (
    <Picker label="Preferred fruit or vegetable" items={options}>
      {section => (
        <PickerSection id={section.name}>
          <Header>
            <Heading>{section.name}</Heading>
            <Text slot="description">These flavors are common</Text>
          </Header>
          <Collection items={section.children}>
            {item => <PickerItem id={item.name}>{item.name}</PickerItem>}
          </Collection>
        </PickerSection>
      )}
    </Picker>
  );
}

Slots

Use the "label" and "description" slots to separate primary and secondary content. Items can also include an icon.

Permissions

import {Picker, PickerItem, Text} from '@react-spectrum/s2';
import Comment from '@react-spectrum/s2/icons/Comment';
import Edit from '@react-spectrum/s2/icons/Edit';
import UserSettings from '@react-spectrum/s2/icons/UserSettings';

<Picker label="Permissions" defaultSelectedKey="read">
  <PickerItem id="read" textValue="Read">
    <Comment />
    <Text slot="label">Read</Text>
    <Text slot="description">Comment only</Text>
  </PickerItem>
  <PickerItem id="write" textValue="Write">
    <Edit />
    <Text slot="label">Write</Text>
    <Text slot="description">Read and write only</Text>
  </PickerItem>
  <PickerItem id="admin" textValue="Admin">
    <UserSettings />
    <Text slot="label">Admin</Text>
    <Text slot="description">Full access</Text>
  </PickerItem>
</Picker>

Links

Use the href prop on a <ListBoxItem> to create a link. See the client side routing guide to learn how to integrate with your framework. Link items in a Picker are not selectable.

Project

import {Picker, PickerItem} from '@react-spectrum/s2';

<Picker label="Project">
  <PickerItem href="https://example.com/" target="_blank">Create new…</PickerItem>
  <PickerItem>Proposal</PickerItem>
  <PickerItem>Budget</PickerItem>
  <PickerItem>Onboarding</PickerItem>
</Picker>

Selection

Setting a selected option can be done by using the defaultSelectedKey or selectedKey prop. The selected key corresponds to the id prop of an item. When Picker is used with a dynamic collection as described above, the id of each item is derived from the data. See the Selection guide for more details.

Pick an animal

You selected Bison

import {Picker, PickerItem} from '@react-spectrum/s2';
import {useState} from 'react';

function Example() {
  let [animal, setAnimal] = useState<Key>("Bison");

  return (
    <>
      <Picker
        label="Pick an animal"
        selectedKey={animal}
        onSelectionChange={selected => setAnimal(selected)}>
        <PickerItem id="Koala">Koala</PickerItem>
        <PickerItem id="Kangaroo">Kangaroo</PickerItem>
        <PickerItem id="Platypus">Platypus</PickerItem>
        <PickerItem id="Bald Eagle">Bald Eagle</PickerItem>
        <PickerItem id="Bison">Bison</PickerItem>
      </Picker>
      <p>You selected {animal}</p>
    </>
  );
}

Validation

Picker supports the isRequired prop to ensure the user selects an option, as well as custom client and server-side validation. It can also be integrated with other form libraries. See the Forms guide to learn more.

import {Picker, PickerItem, ButtonGroup, Button, Form} from '@react-spectrum/s2';

<Form>
  <Picker
    label="Select an animal"
    name="animal"
    isRequired
    description="Please select an animal.">
    <PickerItem>Aardvark</PickerItem>
    <PickerItem>Cat</PickerItem>
    <PickerItem>Dog</PickerItem>
    <PickerItem>Kangaroo</PickerItem>
    <PickerItem>Panda</PickerItem>
    <PickerItem>Snake</PickerItem>
  </Picker>
  <ButtonGroup>
    <Button type="submit">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>

The open state of the Picker can be controlled via the defaultOpen and isOpen props. The align, direction, shouldFlip and menuWidth props control the behavior of the popover.

Select is closed

Choose frequency

align

direction

shouldFlip

menuWidth

import {Picker, PickerItem} from '@react-spectrum/s2';
import {useState} from 'react';

function Example(props) {
  let [open, setOpen] = useState(false);

  return (
    <div>
      <p>Select is {open ? 'open' : 'closed'}</p>
      <Picker
        {...props}
        label="Choose frequency"
        isOpen={open}
        onOpenChange={setOpen}>
        <PickerItem id="rarely">Rarely</PickerItem>
        <PickerItem id="sometimes">Sometimes</PickerItem>
        <PickerItem id="always">Always</PickerItem>
      </Picker>
    </div>
  );
}

Props

Picker

Name	Type	Default
`placeholder`	`string`	Default: `'Select an item' (localized)`
Temporary text that occupies the select when it is empty.
`isDisabled`	`boolean`	Default: —
Whether the input is disabled.
`size`	`'S' \| 'M' \| 'L' \| 'XL'`	Default: `'M'`
The size of the Picker.
`isQuiet`	`boolean`	Default: —
Whether the picker should be displayed with a quiet style.
`styles`	`StylesProp`	Default: —
Spectrum-defined styles, returned by the `style()` macro.

`children`	`ReactNode \| (item: object) => ReactNode`	Default: —
The contents of the collection.
`items`	`Iterable<T>`	Default: —
Item objects in the collection.
`loadingState`	`LoadingState`	Default: —
The current loading state of the Picker.
`onLoadMore`	`() => any`	Default: —
Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.
`dependencies`	`ReadonlyArray<any>`	Default: —
Values that should invalidate the item cache when using dynamic collections.

`selectedKey`	`Key \| null`	Default: —
The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	Default: —
The initial selected key in the collection (uncontrolled).
`onSelectionChange`	`(key: Key \| null) => void`	Default: —
Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	Default: —
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

PickerItem

Name	Type
`children`	`ReactNode`
`id`	`Key`
The unique id of the item.
`value`	`T`
The object value that this item represents. When using dynamic collections, this is set automatically.
`textValue`	`string`
A string representation of the item's contents, used for features like typeahead.
`isDisabled`	`boolean`
Whether the item is disabled.
`styles`	`StylesProp`
Spectrum-defined styles, returned by the `style()` macro.

PickerSection

Name	Type
`id`	`Key`
The unique id of the section.
`value`	`object`
The object value that this section represents. When using dynamic collections, this is set automatically.

`children`	`ReactNode \| (item: object) => ReactElement`
Static child items or a function to render children.
`items`	`Iterable<object>`
Item objects in the section.
`dependencies`	`ReadonlyArray<any>`
Values that should invalidate the item cache when using dynamic collections.

Picker

Content

Slots

Links

Selection

Validation

Popover options

Props

Picker

PickerItem

PickerSection