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:
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!