CustomSelectControl

CustomSelectControl allows users to select an item from a single-option menu just like SelectControl, with the addition of being able to provide custom styles for each item in the menu. This means it does not use a native <select>, so should only be used if the custom styling is necessary.

Table of contents

1. Design guidelines
2. Development guidelines
3. Related components

Design guidelines

These are the same as the ones for SelectControls.

Development guidelines

Usage

/**
 * WordPress dependencies
 */
import { CustomSelectControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

const options = [
	{
		key: 'small',
		name: 'Small',
		style: { fontSize: '50%' },
	},
	{
		key: 'normal',
		name: 'Normal',
		style: { fontSize: '100%' },
	},
	{
		key: 'large',
		name: 'Large',
		style: { fontSize: '200%' },
	},
	{
		key: 'huge',
		name: 'Huge',
		style: { fontSize: '300%' },
	},
];

function MyCustomSelectControl() {
	const [ , setFontSize ] = useState();
	return (
		<CustomSelectControl
			label="Font Size"
			options={ options }
			onChange={ ( { selectedItem } ) => setFontSize( selectedItem ) }
		/>
	);
}

function MyControlledCustomSelectControl() {
	const [ fontSize, setFontSize ] = useState( options[ 0 ] );
	return (
		<CustomSelectControl
			label="Font Size"
			options={ options }
			onChange={ ( { selectedItem } ) => setFontSize( selectedItem ) }
			value={ options.find( ( option ) => option.key === fontSize.key ) }
		/>
	);
}

Props

className

A custom class name to append to the outer <div>.

• Type: String
• Required: No

hideLabelFromVision

Used to visually hide the label. It will always be visible to screen readers.

• Type: Boolean
• Required: No

label

The label for the control.

• Type: String
• Required: Yes

describedBy

Pass in a description that will be shown to screen readers associated with the select trigger button. If no value is passed, the text "Currently selected: selectedItem.name" will be used fully translated.

• Type: String
• Required: No

options

The options that can be chosen from.

• Type: Array<{ key: String, name: String, style: ?{}, className: ?String, ...rest }>
• Required: Yes

onChange

Function called with the control's internal state changes. The selectedItem property contains the next selected item.

• Type: Function
• Required: No

value

Can be used to externally control the value of the control, like in the MyControlledCustomSelectControl example above.

• Type: Object
• Required: No

Related components

• Like this component, but implemented using a native <select> for when custom styling is not necessary, the SelectControl component.

• To select one option from a set, when you want to show all the available options at once, use the Radio component.

• To select one or more items from a set, use the CheckboxControl component.

• To toggle a single setting on or off, use the ToggleControl component.

• If you have a lot of items, ComboboxControl might be a better fit.