TreeSelect

TreeSelect is a form component to choose from hierarchical data.


import { TreeSelectModule } from 'primeng/treeselect';

TreeSelect is used as a controlled component with ng-model directive along with an options collection. Internally Tree component is used so the options model is based on TreeNode API.

In single selection mode, value binding should be the key value of a node.

Select Item

<p-treeSelect 
    class="md:w-20rem w-full" 
    containerStyleClass="w-full" 
    [(ngModel)]="selectedNodes" 
    [options]="nodes" 
    placeholder="Select Item" />

TreeSelect can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.

Select Item

<form [formGroup]="formGroup">
    <p-treeSelect 
        class="md:w-20rem w-full" 
        containerStyleClass="w-full" 
        formControlName="selectedNodes" 
        [options]="nodes" 
        placeholder="Select Item" />
</form>

More than one node is selectable by setting selectionMode to multiple. By default in multiple selection mode, metaKey press (e.g. ⌘) is necessary to add to existing selections however this can be configured with disabling the metaKeySelection property. Note that in touch enabled devices, TreeSelect always ignores metaKey.

In multiple selection mode, value binding should be a key-value pair where key is the node key and value is a boolean to indicate selection.



{
    '0-0': true,
    '0-1-0': true
}

Select Item

<p-treeSelect 
    class="w-full md:w-20rem" 
    containerStyleClass="w-full" 
    [(ngModel)]="selectedNodes" 
    [options]="nodes" 
    [metaKeySelection]="false" 
    selectionMode="multiple"
    placeholder="Select Item" />

Selection of multiple nodes via checkboxes is enabled by configuring selectionMode as checkbox.

Select Item

<p-treeSelect 
    class="w-full md:w-20rem" 
    containerStyleClass="w-full" 
    [(ngModel)]="selectedNodes" 
    [options]="nodes" 
    display="chip" 
    [metaKeySelection]="false" 
    selectionMode="checkbox" 
    placeholder="Select Item" />

VirtualScrolling is an efficient way of rendering the options by displaying a small subset of data in the viewport at any time. When dealing with huge number of options, it is suggested to enable VirtualScrolling to avoid performance issues. Usage is simple as setting virtualScroll property to true and defining virtualScrollItemSize to specify the height of an item.

Select Item

<p-treeSelect 
    class="w-full md:w-20rem" 
    containerStyleClass="w-full" 
    [(ngModel)]="selectedNodes" 
    [options]="nodes" 
    display="chip" 
    [metaKeySelection]="false" 
    selectionMode="checkbox" 
    placeholder="Select Item" 
    [virtualScroll]="true" 
    [virtualScrollItemSize]="46" 
    [virtualScrollOptions]="{scrollHeight: '200px'}" />

Lazy loading is useful when dealing with huge datasets, in this example nodes are dynamically loaded on demand using loading property and onNodeExpand method.

Select Item

<p-treeSelect
    class="w-full"
    containerStyleClass="w-full"
    [(ngModel)]="selectedNodes"
    [loading]="loading"
    (onNodeExpand)="onNodeExpand($event)"
    [options]="nodes"
    display="chip"
    [metaKeySelection]="false"
    selectionMode="checkbox"
    placeholder="Select Item"
    [loading]="loading"
/>

Filtering is enabled by adding the filter property, 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 Item

<p-treeSelect 
    class="md:w-20rem w-full" 
    containerStyleClass="w-full" 
    [(ngModel)]="selectedNodes" 
    [options]="nodes" 
    placeholder="Select Item" 
    [filter]="true" 
    [filterInputAutoFocus]="true" />

A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.

Select Item

<p-floatLabel class="md:w-20rem w-full">
    <p-treeSelect 
        containerStyleClass="w-full" 
        [(ngModel)]="selectedNodes" 
        [options]="nodes" 
        placeholder="Select Item" />
    <label for="treeselect">
        Tree Select
    </label>
</p-floatLabel>

Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.

Select Item

<p-treeSelect 
    class="md:w-20rem w-full" 
    containerStyleClass="w-full" 
    [(ngModel)]="selectedNodes" 
    variant="filled"
    [options]="nodes" 
    placeholder="Select Item" />

Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.

Select Item

<p-treeSelect 
    class="md:w-20rem w-full ng-invalid ng-dirty" 
    containerStyleClass="w-full" 
    [(ngModel)]="selectedNodes" 
    [options]="nodes"
    placeholder="Select Item" />

When disabled is present, the element cannot be edited and focused.

TreeSelect

<p-treeSelect 
    class="md:w-20rem w-full" 
    containerStyleClass="w-full" 
    [(ngModel)]="selectedNodes" 
    [options]="nodes" 
    [disabled]="true" 
    placeholder="TreeSelect" />

Following is the list of structural style classes, for theming classes visit theming page.

NameElement
p-treeselectContainer element.
p-treeselect-label-containerContainer of the label to display selected items.
p-treeselect-labelLabel to display selected items.
p-treeselect-triggerDropdown button.
p-treeselect-panelOverlay panel for items.
p-treeselect-items-wrapperList container of items.

Screen Reader

Value to describe the component can either be provided with ariaLabelledby or ariaLabel 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>
<p-treeSelect ariaLabelledBy="dd1" />

<p-treeSelect ariaLabel="Options" />

Closed State Keyboard Support

KeyFunction
tabMoves focus to the treeselect element.
spaceOpens the popup and moves visual focus to the selected treenode, if there is none then first treenode receives the focus.
down arrowOpens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.

Popup Keyboard Support

KeyFunction
tabMoves focus to the next focusable element in the popup, if there is none then first focusable element receives the focus.
shift + tabMoves focus to the previous focusable element in the popup, if there is none then last focusable element receives the focus.
enterSelects the focused option, closes the popup if selection mode is single.
spaceSelects the focused option, closes the popup if selection mode is single.
escapeCloses the popup, moves focus to the treeselect element.
down arrowMoves focus to the next treenode.
up arrowMoves focus to the previous treenode.
right arrowIf node is closed, opens the node otherwise moves focus to the first child node.
left arrowIf node is open, closes the node otherwise moves focus to the parent node.

Filter Input Keyboard Support

KeyFunction
enterCloses the popup and moves focus to the treeselect element.
escapeCloses the popup and moves focus to the treeselect element.

Close Button Keyboard Support

KeyFunction
enterCloses the popup and moves focus to the treeselect element.
spaceCloses the popup and moves focus to the treeselect element.
escapeCloses the popup and moves focus to the treeselect element.