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

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

Top ↑

Design guidelines Design guidelines

These are the same as the ones for SelectControls.

Top ↑

Development guidelines Development guidelines

Usage Usage

/**
 * WordPress dependencies
 */
import { CustomSelectControl } from "@wordpress/components";
import { useState } from "@wordpress/compose";

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 ) }
        />
    );
}

Top ↑

Props Props

className className

A custom class name to append to the outer <div>.
– Type: String
– Required: No

Top ↑

hideLabelFromVision hideLabelFromVision

Used to visually hide the label. It will always be visible to screen readers.
– Type: Boolean
– Required: No

Top ↑

label label

The label for the control.
– Type: String
– Required: Yes

Top ↑

options options

The options that can be chosen from.
– Type: Array<{ key: String, name: String, style: ?{}, ...rest }>
– Required: Yes

Top ↑

onChange onChange

Function called with the control’s internal state changes. The selectedItem property contains the next selected item.
– Type: Function
– Required: No

Top ↑

value value

Can be used to externally control the value of the control, like in the MyControlledCustomSelectControl example above.
– Type: Object
– Required: No

Top ↑

  • 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.