Select

The Select component implements a theme-able <select/> replacement. It presents a control for picking an option from a list of options in a dropdown menu.

To specify the options available to pick from, you use the Item component. The Item component specifies three main things:

The key of the item, via the key prop.
The rendered content of the item, via the children prop.
The “text value” of the item, so that the item may be selected by typing when the Select is focused, via the textValue prop.

Examples

This is just an example Select component, designed in the Plain Kit project. You have total freedom to design Plume components exactly as you'd want them to be, with your own unique variants and behaviors.

Switch to a different kit:

Plain Kit

There are two ways of specifying the options available to a Select component:

Basic Select

The simplest way is to specify the options as children of the Select component. Note that when the children of Item is just a string, it can also be inferred as the key and the textValue.

Select with Custom Render

An alternative, but more performant way, is to specify possible options as an array of objects to the items prop of Select. You can then specify a render function that renders each item object to an Item instance:

Select Props

Prop	Type	Description
`label`	`React.ReactNode`	Label for the Select; if not specified, then `aria-label` or `aria-labelledby` should be specified.
`children`	`ItemElement[] \| (item: any) => ItemElement`	Either a list of `Item` instances, or, if you're using the `items` prop, a function that takes in an item and returns an `Item` instance
`selectedKey`	`React.Key`	Currently-selected item key (uncontrolled)
`defaultSelectedKey`	`React.Key`	Default selected item key (uncontrolled)
`disallowEmptySelection`	`boolean`	Whether to allow empty selection; defaults to true
`isOpen`	`boolean`	Whether the Select is currently open (controlled)
`defaultOpen`	`boolean`	Whether the Select is by default open (uncontrolled)
`isDisabled`	`boolean`	Whether the Select is disabled
`isReadOnly`	`boolean`	Whether the Select is read-only
`placeholder`	`string`	Text to show when Select is empty
`renderSelectedItem`	`(item: any) => React.ReactNode`	Optional function that takes in a selected item, and returns how it should be rendered in the trigger content
`ref`	`PlumeSelectRef`	Programmatic access to Select

PlumeSelectRef

Method	Description
`focus()`	Focuses this Select’s `trigger` element
`UNSAFE_getDOMNode()`	Returns the root DOM element

useSelectOptionState

You may want to render an option content differently depending on whether is it currently selected, focused, or disabled. For example,

<Select>
  <Item key="CA" textValue="California"><StateFlag state="ca"/></Item>
  <Item key="NY" textValue="New York"><StateFlag state="ny"/></Item>
  <Item key="AZ" textValue="Arizona"><StateFlag state="az"/></Item>
</Select>

Let’s say we have a StateFlag component that renders the state flag of a specific US state as an option. Furthermore, let’s say that we want the StateFlag to be colored when you hover over it, but monochrome when you don’t. StateFag component, then, would need to know whether it is being hovered or not. It can use the useSelectOptionState hook to figure that out:

function StateFlag(props) {
  const {state} = props;
  const {isSelected, isFocused, isDisabled} = useSelectOptionState(state);
  ...
}

SelectOption Props

You should never have to instantiate SelectOption directly, except as the renderOption config to Plume’s useSelect.

Note that the SelectOption is different from the Item component, even though they may seem similar. SelectOption specifies how an option is rendered when displayed in the dropdown menu; it does not understand the content of that option. Item specifies the semantic meaning of each option (the key, the text value, and the opaque rendered content). Item is relevant to people using Select; SelectOption is only relevent to people building Select.

Prop	Type	Description
`itemKey`	`React.Key`	Key for the rendered item
`children`	`React.ReactNode`	Opaque content of the option

The usePlumeSelect hook implements interactivity and accessibility for a Select dropdown component. It is a themable replacement for a select HTML element, and has similar accessibility.

Build your own!

Build your own Select, designed in Plasmic, with the useSelect and useSelectOption hook!