CustomSelectControl Edit
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 Table of contents
Design guidelines Design guidelines
These are the same as the ones for SelectControl
s.
Development guidelines Development guidelines
Usage 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 Props
className className
A custom class name to append to the outer <div>
.
- Type:
String
- Required: No
hideLabelFromVision hideLabelFromVision
Used to visually hide the label. It will always be visible to screen readers.
- Type:
Boolean
- Required: No
label label
The label for the control.
- Type:
String
- Required: Yes
describedBy 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 options
The options that can be chosen from.
- Type:
Array<{ key: String, name: String, style: ?{}, className: ?String, ...rest }>
- Required: Yes
onChange onChange
Function called with the control’s internal state changes. The selectedItem
property contains the next selected item.
- Type:
Function
- Required: No
value value
Can be used to externally control the value of the control, like in the MyControlledCustomSelectControl
example above.
- Type:
Object
- Required: No
Related components Related components
-
Like this component, but implemented using a native
<select>
for when custom styling is not necessary, theSelectControl
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.