TreeSelect

TreeSelect is a form component to choose from hierarchical data.

Import #


import { TreeSelectModule } from 'primeng/treeselect';

Basic #

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" />

Reactive Forms #

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


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

Multiple #

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" />

Checkbox #

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" />

Virtual Scroll #

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 #

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"
/>

Filter #

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" />

Float Label #

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

Select Item

Tree Select


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

Filled #

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 #

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" />

Disabled #

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" />

Style #

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

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 #

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

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.

TreeSelect API

API defines helper props, events and others for the PrimeNG TreeSelect module.

TreeSelect #

TreeSelect is a form component to choose from hierarchical data.

Properties #

Defines the input properties of the component.

name	type	default	description
inputId	string	null	Identifier of the underlying input element.
scrollHeight	string	400px	Height of the viewport, a scrollbar is defined if height of list exceeds this value.
disabled	boolean	false	When present, it specifies that the component should be disabled.
metaKeySelection	boolean	false	Defines how multiple items can be selected, when true metaKey needs to be pressed to select or unselect an item and when set to false selection of each item can be toggled individually. On touch enabled devices, metaKeySelection is turned off automatically.
variant	"outlined" \| "filled"	outlined	Specifies the input variant of the component.
display	"comma" \| "chip"	comma	Defines how the selected items are displayed.
selectionMode	"multiple" \| "checkbox" \| "single"	single	Defines the selection mode.
tabindex	string	0	Index of the element in tabbing order.
ariaLabel	string	null	Defines a string that labels the input for accessibility.
ariaLabelledBy	string	null	Establishes relationships between the component and label(s) where its value should be one or more element IDs.
placeholder	string	null	Label to display when there are no selections.
panelClass	string \| string[] \| Set<string> \| Object	null	Style class of the overlay panel.
panelStyle	Object	null	Inline style of the panel element.
panelStyleClass	string	null	Style class of the panel element.
containerStyle	Object	null	Inline style of the container element.
containerStyleClass	string	null	Style class of the container element.
labelStyle	Object	null	Inline style of the label element.
labelStyleClass	string	null	Style class of the label element.
overlayOptions	OverlayOptions	null	Specifies the options for the overlay.
emptyMessage	string	null	Text to display when there are no options available. Defaults to value from PrimeNG locale configuration.
appendTo	any	null	A valid query selector or an HTMLElement to specify where the overlay gets attached. Special keywords are "body" for document body and "self" for the element itself.
filter	boolean	false	When specified, displays an input field to filter the items.
filterBy	string	label	When filtering is enabled, filterBy decides which field or fields (comma separated) to search against.
filterMode	string	lenient	Mode for filtering valid values are "lenient" and "strict". Default is lenient.
filterPlaceholder	string	null	Placeholder text to show when filter input is empty.
filterLocale	string	null	Locale to use in filtering. The default locale is the host environment's current locale.
filterInputAutoFocus	boolean	true	Determines whether the filter input should be automatically focused when the component is rendered.
propagateSelectionDown	boolean	true	Whether checkbox selections propagate to descendant nodes.
propagateSelectionUp	boolean	true	Whether checkbox selections propagate to ancestor nodes.
showClear	boolean	false	When enabled, a clear icon is displayed to clear the value.
resetFilterOnHide	boolean	true	Clears the filter value when hiding the dropdown.
virtualScroll	boolean	false	Whether the data should be loaded on demand during scroll.
virtualScrollItemSize	number	null	Height of an item in the list for VirtualScrolling.
virtualScrollOptions	ScrollerOptions	null	Whether to use the scroller feature. The properties of scroller component can be used like an object in it.
autofocus	boolean	false	When present, it specifies that the component should automatically get focus on load.
options	TreeNode<any>[]	null	An array of treenodes.
showTransitionOptions	string	null	Transition options of the show animation.
hideTransitionOptions	string	null	Transition options of the hide animation.
loading	boolean	false	Displays a loader to indicate data load is in progress.

Emitters #

Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.

name	parameters	description
onNodeExpand	event : TreeSelectNodeExpandEvent	Callback to invoke when a node is expanded.
onNodeCollapse	event : TreeSelectNodeCollapseEvent	Callback to invoke when a node is collapsed.
onShow	event : Event	Callback to invoke when the overlay is shown.
onHide	event : Event	Callback to invoke when the overlay is hidden.
onClear	value : any	Callback to invoke when input field is cleared.
onFilter	event : TreeFilterEvent	Callback to invoke when data is filtered.
onFocus	event : Event	Callback to invoke when treeselect gets focus.
onBlur	event : Event	Callback to invoke when treeselect loses focus.
onNodeUnselect	event : TreeNodeUnSelectEvent	Callback to invoke when a node is unselected.
onNodeSelect	event : TreeNodeSelectEvent	Callback to invoke when a node is selected.

Templates #

Defines the templates used by the component.

name	parameters	description
value	context : { $implicit: TreeNode, // Value of the component. placeholder: string, // Placeholder of the component. }	Custom value template.
header	context : { $implicit: TreeNode, // Value of the component. options: TreeNode, // Placeholder of the component. }	Custom header template.
empty		Custom empty template.
footer		Custom footer template.
clearicon		Custom clear icon template.
triggericon		Custom dropdown trigger icon template.
filtericon		Custom filter icon template.
closeicon		Custom close icon template.
itemtogglericon	context : { $implicit: boolean, // Expanded state of the node. }	Custom node toggler template.
itemcheckboxicon		Custom node checkbox icon template.
itemloadingicon		Custom loading icon template.

Events #

Defines the custom events used by the component's emitters.

TreeSelectNodeCollapseEvent #

Custom node collapse event.

name	type	description
originalEvent	Event	Browser event.
node	TreeNode<any>	Node instance.

TreeSelectNodeExpandEvent #

Custom node expand event.

name	type	description
originalEvent	Event	Browser event.
node	TreeNode<any>	Node instance.

Interfaces #

Defines the custom interfaces used by the module.

TreeNode #

Represents a node in a tree data structure.

name	type	description
checked	boolean
label	string	Label of the node.
data	T	Data represented by the node.
icon	string	Icon of the node to display next to content.
expandedIcon	string	Icon to use in expanded state.
collapsedIcon	string	Icon to use in collapsed state.
children	TreeNode<T>[]	An array of treenodes as children.
leaf	boolean	Specifies if the node has children. Used in lazy loading.
expanded	boolean	Expanded state of the node.
type	string	Type of the node to match a template.
parent	TreeNode<T>	Parent of the node.
partialSelected	boolean	Defines if value is partially selected.
style	any	Inline style of the node.
styleClass	string	Style class of the node.
draggable	boolean	Defines if the node is draggable.
droppable	boolean	Defines if the node is droppable.
selectable	boolean	Whether the node is selectable when selection mode is enabled.
key	string	Mandatory unique key of the node.
loading	boolean	Defines if the node is loading.