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:

  1. The key of the item, via the key prop.
  2. The rendered content of the item, via the children prop.
  3. 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

PropTypeDescription
labelReact.ReactNodeLabel for the Select; if not specified, then aria-label or aria-labelledby should be specified.
childrenItemElement[] | (item: any) => ItemElementEither 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
selectedKeyReact.KeyCurrently-selected item key (uncontrolled)
defaultSelectedKeyReact.KeyDefault selected item key (uncontrolled)
disallowEmptySelectionbooleanWhether to allow empty selection; defaults to true
isOpenbooleanWhether the Select is currently open (controlled)
defaultOpenbooleanWhether the Select is by default open (uncontrolled)
isDisabledbooleanWhether the Select is disabled
isReadOnlybooleanWhether the Select is read-only
placeholderstringText to show when Select is empty
renderSelectedItem(item: any) => React.ReactNodeOptional function that takes in a selected item, and returns how it should be rendered in the trigger content
refPlumeSelectRefProgrammatic access to Select

PlumeSelectRef

MethodDescription
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.

PropTypeDescription
itemKeyReact.KeyKey for the rendered item
childrenReact.ReactNodeOpaque 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!