Automattic Design System

CustomSelectControl

CustomSelectControl is a dropdown for selecting a single option from a list, with support for custom styling. Use it instead of the SelectControl when options need richer markup (e.g. per-option styles or hints).

import { CustomSelectControl } from '@wordpress/components';

LinksPermalink to this section

View on Storybook

View source on GitHub

PropsPermalink to this section

Name	Default	Description
`className`		`string` Optional classname for the component.
`hideLabelFromVision`		`boolean` Hide the label visually, while keeping available to assistive technology.
`describedBy`		`string` Description for the select trigger button used by assistive technology. If no value is passed, the text “Currently selected: selectedItem.name” will be used fully translated.
`label` Required		`string` Label for the control.
`onChange`		`(newValue: CustomSelectChangeObject<NoInfer<CustomSelectOption>>) => void` Function called with the control’s internal state changes. The `selectedItem` property contains the next selected item.
`onBlur`		`FocusEventHandler<HTMLButtonElement>` A handler for `blur` events on the trigger button.
`onFocus`		`FocusEventHandler<HTMLButtonElement>` A handler for `focus` events on the trigger button.
`onMouseOut`		`MouseEventHandler<HTMLButtonElement>` A handler for `mouseout` events on the trigger button.
`onMouseOver`		`MouseEventHandler<HTMLButtonElement>` A handler for `mouseover` events on the trigger button.
`options` Required		`readonly CustomSelectOption[]` The list of options that can be chosen from.
`size`	`'default'`	`"small" \| "default"` The size of the control.
`value`		`NoInfer<CustomSelectOption>` Can be used to externally control the value of the control.
`__experimentalShowSelectedHint`		`boolean` Use the `showSelectedHint` property instead.
`showSelectedHint`	`false`	`boolean` Show the hint of the selected item in the trigger button.
`__nextUnconstrainedWidth`		`boolean` Opt-in prop for an unconstrained width style which became the default in WordPress 6.5. The prop is no longer needed and can be safely removed.
`__next40pxDefaultSize`		`boolean` Start opting into the larger default height that will become the default size in a future version.

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = ( props ) => {
	const [ value, setValue ] = useState( props.options[ 0 ] );

	const onChange: React.ComponentProps<
		typeof CustomSelectControl
	>[ 'onChange' ] = ( changeObject ) => {
		setValue( changeObject.selectedItem );
		props.onChange?.( changeObject );
	};

	return (
		<CustomSelectControl
			{ ...props }
			onChange={ onChange }
			value={ value }
		/>
	);
};

With Long LabelsPermalink to this section

const WithLongLabels = ( props ) => {
	const [ value, setValue ] = useState( props.options[ 0 ] );

	const onChange: React.ComponentProps<
		typeof CustomSelectControl
	>[ 'onChange' ] = ( changeObject ) => {
		setValue( changeObject.selectedItem );
		props.onChange?.( changeObject );
	};

	return (
		<CustomSelectControl
			{ ...props }
			onChange={ onChange }
			value={ value }
		/>
	);
};

With HintsPermalink to this section

const WithHints = ( props ) => {
	const [ value, setValue ] = useState( props.options[ 0 ] );

	const onChange: React.ComponentProps<
		typeof CustomSelectControl
	>[ 'onChange' ] = ( changeObject ) => {
		setValue( changeObject.selectedItem );
		props.onChange?.( changeObject );
	};

	return (
		<CustomSelectControl
			{ ...props }
			onChange={ onChange }
			value={ value }
		/>
	);
};