Select

Importing

import { Select } from '@customerio/pluma-components/react';

Usage

To use the Select component, pass in the following props:

• label - a string label to render above the select
  • alternatively, ariaLabelledby or ariaLabel may be used
• value - the string value of the currently selected option
• onChange - a callback to set the value state
• options - an array of objects to render in the select dropdown menu. The objects should contain the following keys:
  • value - a string value, which corresponds to the value prop
  • label - a string text label to render in the dropdown menu
  • description - optional, a string with additional descriptive text to display below the label
  • searchLabel - optional, a string used for searching the options (if different than the label)
  • icon - a PlumaIcon name to render next to the option
  • isDisabled - optional, whether this options should be disabled (not selectable)
  • tooltip - optional, a string tooltip to show on hover
  • withTruncatedTooltip - optional, automatically show a tooltip when the label is truncated
• placeholder - a placeholder value to show when no option is selected
• icon - optional, a PlumaIcon name to render on the left side of the select trigger

Multiple values

A Select component can be used to select multiple values, which can be enabled via the isMulti prop.

When isMulti is true, there are two important differences from the single value case:

• the value prop is an array of strings (the values of the selected options)
• the onChange callback is called with an array of strings

Options with descriptions

You can add descriptive text below an option's label:

Custom elements

Options carry their own elementBefore and elementAfter. elementBefore renders in the option's leading slot, after the option icon if one is set; elementAfter renders in the trailing slot, beside the checkmark shown when the option is selected — so a selected and an unselected row still line up.

The select trigger takes the same two props: elementBefore renders after the trigger's icon and before the selected value, and elementAfter renders after the clear button and before the chevron.

In React both are nodes. In Ember, an option's slots are components (options are plain data, so they can't take a block), while the trigger also accepts :elementBefore and :elementAfter named blocks.

Deprecated variations

unsafe_leftSectionComponent on the trigger is deprecated. It still works and renders in the same place, but elementBefore is the supported equivalent — and in Ember it can also be filled with a named block.

// Deprecated
<Select label="Region" unsafe_leftSectionComponent={<Badge color="neutral">US</Badge>} options={options} />

// Supported
<Select label="Region" elementBefore={<Badge color="neutral">US</Badge>} options={options} />

Disabling options

Individual options can be disabled:

Searchable selects

Enabling isSearchable on the component will render a search input inside the select dropdown, which allows users to filter the options:

Creating new options

When using a searchable Select, you can allow users to create new options when their search doesn't match any existing options. This is useful for fields like tags, categories, or any user-defined values where the list of options should be dynamic.

Enable this feature with the withCreate and onCreate props:

• withCreate - enables the "Create new" option when no exact match is found
• onCreate - callback that receives the search value when "Create new" is selected
• createOptionLabel - optional custom label for the "Create new" option (default: Create "{value}")
  • this can be a string, or a function which receives the current search string, and returns a string to show
• canCreateNewOption - optional function to control when the "Create new" option appears
  • can be used to hide the "Create new" option for certain values

Custom create option label

The label shown for the "Create new" option can be customized using the createOptionLabel prop. It accepts a string or a function that receives the search value:

Restricting which values can be created

The canCreateNewOption callback can be used to control whether specific values should show/not show the "Create new" option, for example if we want to prevent creation of items that have special names.

Select groups

You can pass in groups of options to the selects to create breaks between sets of options:

Disabling groups

An entire group can be disabled by setting its option entry to isDisabled:

Collapsible groups

The Select component supports making groups collapsible - where clicking on the group's header will collapse/expand the group. This is enabled by including an isCollapsible key on the group's object - when set to true, that group will be collapsible.

Additionally, the defaultIsCollapsed key can be used to make a group collapsed by default when first opening the dropdown.

Virtualized rendering

For very long lists of options (hundreds, thousands of items), rendering the dropdown content may become very slow. For these cases, the Select component supports rendering "virtualized" lists, i.e. it will only render a small subset of options within the dropdown, and will update accordingly as users scroll through it.

For virtualization we use the TanStack Virtual library (both in Ember and React).

This option is disabled by default, and can be enabled via the withVirtualizer argument. Optionally, the virtualizerOptions argument accepts the same options as the library's Virtualizer class, allowing you to customize the behavior if necessary.

Custom value and option components

The Select component accepts valueComponent, optionItemComponent, and optionComponent props, which can be used to customize how the selected value, and the options in the dropdown, are rendered.

To use them, you will need to pass in a component as the prop.

valueComponent is the component that will be used to render the selected value in the Select's trigger. It will be called with the following props:

• option - the option object from the options array

optionItemComponent is the component that renders each option button in the dropdown. This needs to be customized carefully, as this is the component to which various events and props are attached, to support features like keyboard navigation, focus management, and accessibility via aria props. Pluma also exports a SelectMenuOptionButton component, which is the one used internally for these options. When customizing, it is recommended to use this component as a base to make sure the basic styling and behavior is preserved. This component is called with:

• option - the option object from the options array
• isSelected - whether this is the currently selected option (the value matches this option)
• isActive - whether this is the currently active option (it's currently hovered or focused via keyboard)
• isDisabled - whether this option is disabled
• index - the index of this option in the list
• level - the nesting level of this option
• collapsibleParentsCount - the number of collapsible parent groups (this, and the one below, are used internally to apply the correct padding to nested options))
• nonCollapsibleParentsCount - the number of non-collapsible parent groups
• labelRef - (only in React) a ref to an element inside the option that could become truncated - this is used to detect when an option is truncated to optionally show a tooltip
• setLabelElement - (only in Ember) like above, but for Ember - a callback to set the potentially truncated element
• optionComponent - the component that renders this element's contents

optionComponent is the content rendered inside the option button (inside optionItemComponent). It will be called with the following props:

• option - the option object from the options array
• isSelected - whether this is the currently selected option (the value matches this option)
• isActive - whether this is the currently active option (it's currently hovered or focused via keyboard)
• labelRef - (only in React) a ref to an element inside the option that could become truncated - this is used to detect when an option is truncated to optionally show a tooltip
• setLabelElement - (only in Ember) like above, but for Ember - a callback to set the potentially truncated element If you intend to enable withTruncatedTooltip on a customized optionComponent, it is required to set the labelRef (in React) or call setLabelElement (in Ember) with the element that might get truncated - otherwise the tooltip won't be able to detect the truncation.

The same component may be used for both valueComponent and optionComponent.

For example, we might define a custom option component like this:

const COLORS = [
	'red',
	'raspberry',
	'clementine',
	'yellow',
	'green',
	'teal',
	'blue',
	'plum',
	'purple',
	'grey',
	'outline',
];

function getIndex(option) {
	return birdOptions.findIndex((o) => o.value === option.value);
}

function CustomOptionComponent({ option, isSelected }) {
	const originalIndex = getIndex(option);

	return (
		<InlineStack alignInline="space-between" alignBlock="center" gap="100">
			<Label 
				color={COLORS[originalIndex % COLORS.length]}
			>
				{option.label}
			</Label>
			{isSelected ? <SelectMenuOptionSelectedIcon /> : null}
		</InlineStack>
	);
}

Which could then be used in the Select component:

Custom icon component

You may find that customizing the entire option may be too heavy-handed. Instead, you may just need to customize the icon area that prefixes the option. For such cases, the Select component also accepts an iconComponent prop, which can be used to customize how the icons next to the options are rendered.

To use iconComponent, you will need to pass in a component as the prop.

iconComponent will be called with the following props:

• name - the name of the icon (this value will be the same as icon on the option)
• isSelected - whether the option this icon is a part of is currently selected
• size - the size of the control (which will either be sm or md, as per the size prop)

For example, we might define a custom icon component like this:

export const CustomIconComponent = ({ name, isSelected }) => {
	const color = isSelected ? "success" : "critical";
	
	return (
		<Avatar statusIndicatorColor={color} name={name}>
		</Avatar>
	);
}

Which could then be used in the Select component:

Options with tooltips

Individual options can display a tooltip on hover by setting the tooltip property on the option object.

The tooltip placement can be customized with tooltipPlacement (defaults to 'right'), though it's recommended to avoid using top or bottom placements, as they would overlap with other options in the dropdown and make it more difficult to navigate.

Truncation tooltips

When options may have long labels that get truncated by CSS, setting withTruncatedTooltip to true on the option will automatically show a tooltip only when the label text is actually truncated. The tooltip content defaults to the option's label, but can be overridden by also setting tooltip.

Rich tooltip content

When you need tooltips with rich content like links or formatted text, use the optionItemComponent prop to wrap the default SelectMenuOptionButton with a custom Tooltip.

Asynchronous loading

The Select component supports loading options data asynchronously. It will display a loading spinner inside the input when isLoading is true. When performing filtering through an API, you will also have to control the search input state via the searchInputValue and onSearchInput props (otherwise the component will perform filtering internally).

Select also supports infinite scrolling (for paginated APIs), and will call the onLoadMore callback when scrolling towards the end of the list. The other props expected for this use case are:

• shouldLoadMore - a boolean indicating whether the onLoadMore callback should be called at all (e.g. when there is a next page of data). Set to false if there are no more pages/there is no more data to fetch
• isLoadingMore - whether more data is currently being fetched. While the API call issued via the onLoadMore callback is running, this should be true, and will show a loading spinner at the bottom of the list

Note: It is up to you to merge the results of the paginated API calls into one options array, which you pass into the component. The component itself only issues callbacks when required, but you control the state.

The example below shows a Select that simulates an API with filtering and pagination.

Palette regions

The dropdown is rendered by SelectPalette, which adds four optional regions around the options list: a header (title, meta slot, close button and the search input), a categories rail on the left, a detail pane on the right that follows the highlighted option, and a footer.

Every region is off unless you configure it, so a Select with none of these props renders exactly what it always did.

Two things worth knowing before you reach for these:

• The rail does not filter the options. It reports which category is active; you pass options that already match.
• paletteFooterComponent takes precedence over footerComponent when both are set.

See the SelectPalette docs for the region context shapes, how to replace a region's contents, and how to open a palette from a plain button.

PlumaProvider configuration

By default, the Select component enters and exits with a CSS transition animation (with a duration of 125ms).

The value can be overridden globally with the componentConfig prop on the PlumaProvider component:

<PlumaProvider
	componentConfig={{
		PlumaSelect: {
			menuAnimationTransitionDuration: 0,
		}
	}}
>
	{children}
</PlumaProvider>

This can be used, for example, in tests, to set the transition time to 0.

Customizing labels

If a string label is not sufficient, a component can be used to render the label.

Customizing descriptions

If a string description is not sufficient, a component can be used to render the description.

Customizing errors

If a string error is not sufficient, a component can be used to render the error.

Clearable

PlumaSelect accepts an isClearable prop, which renders a "clear" button when it has a value. When the button is clicked, the onChange callback is called with null.