See the WordPress Storybook for more detailed, interactive documentation.

Generates a hierarchical select input.

import { useState } from 'react';
import { TreeSelect } from '@wordpress/components';

const MyTreeSelect = () => {
    const [ page, setPage ] = useState( 'p21' );

    return (
        <TreeSelect
            __next40pxDefaultSize
            label="Parent page"
            noOptionLabel="No parent page"
            onChange={ ( newPage ) => setPage( newPage ) }
            selectedId={ page }
            tree={ [
                {
                    name: 'Page 1',
                    id: 'p1',
                    children: [
                        { name: 'Descend 1 of page 1', id: 'p11' },
                        { name: 'Descend 2 of page 1', id: 'p12' },
                    ],
                },
                {
                    name: 'Page 2',
                    id: 'p2',
                    children: [
                        {
                            name: 'Descend 1 of page 2',
                            id: 'p21',
                            children: [
                                {
                                    name: 'Descend 1 of Descend 1 of page 2',
                                    id: 'p211',
                                },
                            ],
                        },
                    ],
                },
            ] }
        />
    );
}

Props

__next40pxDefaultSize

• Type: boolean
• Required: No
• Default: false

Start opting into the larger default height that will become the default size in a future version.

children

• Type: ReactNode
• Required: No

As an alternative to the options prop, optgroups and options can be
passed in as children for more customizability.

disabled

• Type: boolean
• Required: No
• Default: false

If true, the input will be disabled.

hideLabelFromVision

• Type: boolean
• Required: No
• Default: false

If true, the label will only be visible to screen readers.

help

• Type: ReactNode
• Required: No

Additional description for the control.

Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an aria-describedby attribute.

label

• Type: ReactNode
• Required: No

If this property is added, a label will be generated using label property as the content.

labelPosition

• Type: "top" | "bottom" | "side" | "edge"
• Required: No
• Default: 'top'

The position of the label.

noOptionLabel

• Type: string
• Required: No

If this property is added, an option will be added with this label to represent empty selection.

onChange

• Type: ((value: string, extra?: { event?: ChangeEvent<HTMLSelectElement>; }) => void) | undefined
• Required: No

A function that receives the value of the new option that is being selected as input.

options

• Type: readonly ({ label: string; value: string; } & Omit<OptionHTMLAttributes<HTMLOptionElement>, "label" | "value">)[]
• Required: No

An array of option property objects to be rendered,
each with a label and value property, as well as any other
<option> attributes.

prefix

• Type: ReactNode
• Required: No

Renders an element on the left side of the input.

By default, the prefix is aligned with the edge of the input border, with no padding.
If you want to apply standard padding in accordance with the size variant, wrap the element in
the provided <InputControlPrefixWrapper> component.

import {
  __experimentalInputControl as InputControl,
  __experimentalInputControlPrefixWrapper as InputControlPrefixWrapper,
} from '@wordpress/components';

<InputControl
  prefix={<InputControlPrefixWrapper>@</InputControlPrefixWrapper>}
/>

selectedId

• Type: string
• Required: No

The id of the currently selected node.

size

• Type: "default" | "small" | "compact" | "__unstable-large"
• Required: No
• Default: 'default'

Adjusts the size of the input.

suffix

• Type: ReactNode
• Required: No

Renders an element on the right side of the input.

By default, the suffix is aligned with the edge of the input border, with no padding.
If you want to apply standard padding in accordance with the size variant, wrap the element in
the provided <InputControlSuffixWrapper> component.

import {
  __experimentalInputControl as InputControl,
  __experimentalInputControlSuffixWrapper as InputControlSuffixWrapper,
} from '@wordpress/components';

<InputControl
  suffix={<InputControlSuffixWrapper>%</InputControlSuffixWrapper>}
/>

tree

• Type: Tree[]
• Required: No

An array containing the tree objects with the possible nodes the user can select.

variant

• Type: "default" | "minimal"
• Required: No
• Default: 'default'

The style variant of the control.