TreeSelect

TreeSelect is a form component to choose from hierarchical data.

Basic#

TreeSelect component requires an array of TreeNode objects as its options and keys of the nodes as its value.

Select Item


<TreeSelect value={selectedNodeKey} options={nodes} onChange={(e) => setSelectedNodeKey(e.value)} className="md:w-20rem w-full" placeholder="Select Item"></TreeSelect>

Multiple#

TreeSelect supports "single", "multiple" and "checkbox" selection modes. Define selectionMode, value and onChange properties to control the selection. In single mode, selectionKeys should be a single value whereas in multiple or checkbox modes an object is required. By default in multiple selection mode, metaKey is necessary to add to existing selections however this can be configured with metaKeySelection property. Note that in touch enabled devices, Tree does not require metaKey.

Select Items


<TreeSelect value={selectedNodeKeys} options={nodes} onChange={(e) => setSelectedNodeKeys(e.value)} className="md:w-20rem w-full" selectionMode="multiple" metaKeySelection={false} placeholder="Select Items"></TreeSelect>

Checkbox#

Value passed to and from the TreeSelect via the value property should be a an object with key-value pairs where key is the node key and value is a boolean to indicate selection. On the other hand in "checkbox" mode, instead of a boolean, value should be an object that has "checked" and "partialChecked" properties to represent the checked state of a node. Best way to clarify it is prepopulating a TreeSelect with an existing value.

Select Items


<TreeSelect value={selectedNodeKeys} options={nodes} onChange={(e) => setSelectedNodeKeys(e.value)} display="chip" selectionMode="checkbox" className="md:w-20rem w-full" placeholder="Select Items"></TreeSelect>

Filter#

Filtering is enabled by setting the filter property to true, by default label property of a node is used to compare against the value in the text field, in order to customize which field(s) should be used during search define filterBy property. In addition filterMode specifies the filtering strategy. In lenient mode when the query matches a node, children of the node are not searched further as all descendants of the node are included. On the other hand, in strict mode when the query matches a node, filtering continues on all descendants.

Select Items


<TreeSelect value={selectedNodeKey} options={nodes} onChange={(e) => setSelectedNodeKey(e.value)} filter className="md:w-20rem w-full" placeholder="Select Items"></TreeSelect>

Default Value#

Select Item


<TreeSelect value={selectedNodeKey} options={nodes} onChange={(e) => setSelectedNodeKey(e.value)} className="md:w-20rem w-full" placeholder="Select Item"></TreeSelect>

Programmatic#

Label of an option is used as the display text of an item by default, for custom content support define a valueTemplate that gets the selected nodes as a parameter. For custom filter support define a filterTemplatefunction that gets the option instance as a parameter and returns the content for the filter element. In addition header, footer and emptyMessage templates are provided for further customization.

Select Items


<TreeSelect
value={selectedNodeKeys}
options={nodes}
expandedKeys={expandedKeys}
onToggle={(e) => setExpandedKeys(e.value)}
onChange={(e) => setSelectedNodeKeys(e.value)}
display="chip"
selectionMode="checkbox"
className="md:w-20rem w-full"
placeholder="Select Items"
></TreeSelect>
<div className="mb-4 mt-2">
    <Button type="button" icon="pi pi-plus" label="Expand All" onClick={expandAll} className="mr-2" />
    <Button type="button" icon="pi pi-minus" label="Collapse All" onClick={collapseAll} />
</div>

Float Label#

empty

TreeSelect


<TreeSelect inputId="treeselect" value={selectedNodeKey} options={nodes} onChange={(e) => setSelectedNodeKey(e.value)} className="md:w-20rem w-full"></TreeSelect>
<label htmlFor="treeselect">TreeSelect</label>

Invalid#

TreeSelect component requires an array of TreeNode objects as its options and keys of the nodes as its value.

Select Item


<TreeSelect value={selectedNodeKey} options={nodes} onChange={(e) => setSelectedNodeKey(e.value)} className="md:w-20rem w-full p-invalid" placeholder="Select Item"></TreeSelect>

Disabled#

Select Item


<TreeSelect disabled className="md:w-20rem w-full" placeholder="Select Item"></TreeSelect>

Form#

Compatibility with popular React form libraries.

Formik#

Formik is a popular library for handling forms in React.


<Toast ref={toast} />
<TreeSelect
    id="item"
    name="item"
    value={formik.values.item}
    options={node}
    optionLabel="name"
    placeholder="Select Item"
    className={classNames({ 'p-invalid': isFormFieldInvalid('item') })}
    onChange={(e) => {
        formik.setFieldValue('item', e.value);
    }}
/>
{getFormErrorMessage('item')}
<Button type="submit" label="Submit" />

Hook Form#

React Hook Form is another popular React library to handle forms.


<Toast ref={toast} />
<Controller
    name="value"
    control={form.control}
    rules={{ required: 'Value is required.' }}
    render={({ field, fieldState }) => (
        <>
            <TreeSelect id={field.name} value={field.value} onChange={field.onChange} inputRef={field.ref} options={nodes} placeholder="Select Item" className={classNames({ 'p-invalid': fieldState.error })} />
            {getFormErrorMessage(field.name)}
        </>
    )}
/>
<Button label="Submit" type="submit" icon="pi pi-check" />

Style#

Following is the list of structural style classes

Name	Element
p-treeselect	Container element.
p-treeselect-label-container	Container of the label to display selected items.
p-treeselect-label	Label to display selected items.
p-treeselect-trigger	Dropdown button.
p-treeselect-panel	Overlay panel for items.
p-treeselect-items-wrapper	List container of items.

Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility#

Screen Reader

Value to describe the component can either be provided with aria-labelledby or aria-label props. The treeselect element has a combobox role in addition to aria-haspopup and aria-expanded attributes. The relation between the combobox and the popup is created with aria-controls that refers to the id of the popup.

The popup list has an id that refers to the aria-controls attribute of the combobox element and uses tree as the role. Each list item has a treeitem role along with aria-label, aria-selected and aria-expanded attributes. In checkbox selection, aria-checked is used instead of aria-selected. Checkbox and toggle icons are hidden from screen readers as their parent element with treeitem role and attributes are used instead for readers and keyboard support. The container element of a treenode has the group role. The aria-setsize, aria-posinset and aria-level attributes are calculated implicitly and added to each treeitem.

If filtering is enabled, filterInputProps can be defined to give aria-* props to the filter input element.


<span id="dd1">Options</span>
<TreeSelect aria-labelledby="dd1" />

<TreeSelect aria-label="Options" />

Closed State Keyboard Support

Key	Function
tab	Moves focus to the treeselect element.
space	Opens the popup and moves visual focus to the selected treenode, if there is none then first treenode receives the focus.
down arrow	Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.

Popup Keyboard Support

Key	Function
tab	Moves focus to the next focusable element in the popup, if there is none then first focusable element receives the focus.
shift + tab	Moves focus to the previous focusable element in the popup, if there is none then last focusable element receives the focus.
enter	Selects the focused option, closes the popup if selection mode is single.
space	Selects the focused option, closes the popup if selection mode is single.
escape	Closes the popup, moves focus to the treeselect element.
down arrow	Moves focus to the next treenode.
up arrow	Moves focus to the previous treenode.
right arrow	If node is closed, opens the node otherwise moves focus to the first child node.
left arrow	If node is open, closes the node otherwise moves focus to the parent node.

Filter Input Keyboard Support

Key	Function
enter	Closes the popup and moves focus to the treeselect element.
escape	Closes the popup and moves focus to the treeselect element.

Close Button Keyboard Support

Key	Function
enter	Closes the popup and moves focus to the treeselect element.
space	Closes the popup and moves focus to the treeselect element.
escape	Closes the popup and moves focus to the treeselect element.

API#

Visit the API documentation for detailed information about all the properties, events and methods of the component.

TreeSelect