SelectControl Edit
SelectControl allow users to select from a single-option menu. It functions as a wrapper around the browser’s native <select>
element.
Table of contents Table of contents
Design guidelines Design guidelines
Usage Usage
When to use a select control When to use a select control
Use a select control when:
- You want users to select a single option from a list.
- There is a strong default option.
- There is little available space.
- The contents of the hidden part of the menu are obvious from its label and the one selected item. For example, if you have an option menu labelled “Month:” with the item “January” selected, the user might reasonably infer that the menu contains the 12 months of the year without having to look.
If you have a shorter list of options, or need all of the options visible to the user, consider using RadioControl instead.
Do
Use selects when you have multiple options, and can only choose one.
Don’t
Use selects for binary questions.
Behavior Behavior
A SelectControl includes a double-arrow indicator. The menu appears layered over the select.
Opening and Closing Opening and Closing
Once the menu is displayed onscreen, it remains open until the user chooses a menu item, clicks outside of the menu, or switches to another browser tab.
Content Guidelines Content Guidelines
Labels Labels
Label the SelectControl with a text label above it, or to its left, using sentence capitalization. Clicking the label allows the user to focus directly on the select.
Do
Position the label above, or to the left of, the select.
Don’t
Position the label centered over the select, or right aligned against the side of the select.
Menu Items
- Menu items should be short — ideally, single words — and use sentence capitalization.
- Do not use full sentences inside menu items.
- Ensure that menu items are ordered in a way that is most useful to users. Alphabetical or recency ordering is preferred.
Do
Use short menu items.
Don’t
Use sentences in your menu.
Development guidelines Development guidelines
Usage Usage
Render a user interface to select the size of an image.
import { SelectControl } from '@wordpress/components'; import { useState } from '@wordpress/element'; const MySelectControl = () => { const [ size, setSize ] = useState( '50%' ); return ( <SelectControl label="Size" value={ size } options={ [ { label: 'Big', value: '100%' }, { label: 'Medium', value: '50%' }, { label: 'Small', value: '25%' }, ] } onChange={ ( newSize ) => setSize( newSize ) } /> ); };
Render a user interface to select multiple users from a list.
<SelectControl multiple label={ __( 'Select some users:' ) } value={ this.state.users } // e.g: value = [ 'a', 'c' ] onChange={ ( users ) => { this.setState( { users } ); } } options={ [ { value: null, label: 'Select a User', disabled: true }, { value: 'a', label: 'User A' }, { value: 'b', label: 'User B' }, { value: 'c', label: 'User c' }, ] } />
Props Props
- The set of props accepted by the component will be specified below.
- Props not included in this set will be applied to the select element.
- One important prop to refer is
value
. Ifmultiple
istrue
,value
should be an array with the values of the selected options. - If
multiple
isfalse
,value
should be equal to the value of the selected option.
label label
If this property is added, a label will be generated using label property as the content.
- Type:
String
- Required: No
labelPosition labelPosition
The position of the label (top
, side
, or bottom
).
- Type:
String
- Required: No
hideLabelFromVision hideLabelFromVision
If true, the label will only be visible to screen readers.
- Type:
Boolean
- Required: No
help help
If this property is added, a help text will be generated using help property as the content.
- Type:
String|WPElement
- Required: No
multiple multiple
If this property is added, multiple values can be selected. The value passed should be an array.
- Type:
Boolean
- Required: No
options options
An array of objects containing the following properties:
label
: (string) The label to be shown to the user.value
: (Object) The internal value used to choose the selected value. This is also the value passed to onChange when the option is selected.disabled
: (boolean) Whether or not the option should have the disabled attribute.- Type:
Array
- Required: No
onChange onChange
A function that receives the value of the new option that is being selected as input.
If multiple is true the value received is an array of the selected value.
If multiple is false the value received is a single value with the new selected value.
- Type:
function
- Required: Yes
Related components Related components
- To select one option from a set, and you want to show them 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.