TreeSelect

TreeSelect is a form component to choose from hierarchical data.

Import #


import { TreeSelect } 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-80 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-80 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-80" 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-80" 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-80" 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 md:w-80" 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-80 w-full" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" placeholder="Select Item" [filter]="true" [filterInputAutoFocus]="true" />

Template #

TreeSelect offers multiple templates for customization through templating.

Select Item


<p-treeselect class="md:w-80 w-full" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" placeholder="Select Item">
    <ng-template #dropdownicon>
        <i class="pi pi-search"></i>
    </ng-template>
    <ng-template #header>
        <div class="font-medium px-3 py-2">Available Files</div>
    </ng-template>
    <ng-template #footer>
        <div class="px-3 pt-1 pb-2 flex justify-between">
            <p-button label="Add New" severity="secondary" text size="small" icon="pi pi-plus" />
            <p-button label="Remove All" severity="danger" text size="small" icon="pi pi-plus" />
        </div>
    </ng-template>
</p-treeselect>

Float Label #

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

empty

Over Label

empty

In Label

empty

On Label


<p-floatlabel class="w-full md:w-80">
    <p-treeselect [(ngModel)]="value1" inputId="over_label" [options]="nodes" class="w-full" containerStyleClass="w-full" />
    <label for="over_label">Over Label</label>
</p-floatlabel>

<p-floatlabel class="w-full md:w-80" variant="in">
    <p-treeselect [(ngModel)]="value2" inputId="in_label" [options]="nodes" class="w-full" containerStyleClass="w-full" />
    <label for="in_label">In Label</label>
</p-floatlabel>

<p-floatlabel class="w-full md:w-80" variant="on">
    <p-treeselect [(ngModel)]="value3" inputId="on_label" [options]="nodes" class="w-full" containerStyleClass="w-full" />
    <label for="on_label">On Label</label>
</p-floatlabel>

Ifta Label #

IftaLabel is used to create infield top aligned labels. Visit IftaLabel documentation for more information.

empty

File


<p-iftalabel class="w-full md:w-80">
    <p-treeselect [(ngModel)]="selectedValue" inputId="t_file" [options]="nodes" class="w-full" containerStyleClass="w-full" />
    <label for="t_file">File</label>
</p-iftalabel>

Sizes #

TreeSelect provides small and large sizes as alternatives to the base.

Small

Normal

Large


<p-treeselect [(ngModel)]="value1" [options]="nodes" size="small" placeholder="Small" class="md:w-80 w-full" containerStyleClass="w-full" />
<p-treeselect [(ngModel)]="value2" [options]="nodes" placeholder="Normal" class="md:w-80 w-full" />
<p-treeselect [(ngModel)]="value3" [options]="nodes" size="large" placeholder="Large" class="md:w-80 w-full" containerStyleClass="w-full" />

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-80 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-80 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-80 w-full" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" [disabled]="true" placeholder="TreeSelect" />

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.

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	"filled" \| "outlined"	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.
fluid	boolean	false	Spans 100% width of the container when enabled.
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.
size	"small" \| "large"	null	Defines the size of the component.
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.

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	value : any	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.

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.

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

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

TreeSelect

Import #

Basic #

Reactive Forms #

Multiple #

Checkbox #

Virtual Scroll #

Lazy #

Filter #

Template #

Float Label #

Ifta Label #

Sizes #

Filled #

Invalid #

Disabled #

Accessibility #

Screen Reader

Closed State Keyboard Support

Popup Keyboard Support

Filter Input Keyboard Support

Close Button Keyboard Support

TreeSelect API

TreeSelect #

Properties #

Emitters #

Templates #

Events #

TreeSelectNodeCollapseEvent #

TreeSelectNodeExpandEvent #

Interfaces #

TreeNode #

TreeSelect Theming

CSS Classes #

TreeSelect Design Tokens #

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	Mandatory unique key of the node.

class	description
p-treeselect	Class name of the root element
p-treeselect-label-container	Class name of the label container element
p-treeselect-label	Class name of the label element
p-treeselect-chip-item	Class name of the chip item element
p-treeselect-chip	Class name of the chip element
p-treeselect-dropdown	Class name of the dropdown element
p-treeselect-dropdown-icon	Class name of the dropdown icon element
p-treeselect-overlay	Class name of the panel element
p-treeselect-tree-container	Class name of the tree container element
p-treeselect-empty-message	Class name of the empty message element

token	variable	description
root.background	--p-treeselect-background	Background of root
root.disabledBackground	--p-treeselect-disabled-background	Disabled background of root
root.filledBackground	--p-treeselect-filled-background	Filled background of root
root.filledHoverBackground	--p-treeselect-filled-hover-background	Filled hover background of root
root.filledFocusBackground	--p-treeselect-filled-focus-background	Filled focus background of root
root.borderColor	--p-treeselect-border-color	Border color of root
root.hoverBorderColor	--p-treeselect-hover-border-color	Hover border color of root
root.focusBorderColor	--p-treeselect-focus-border-color	Focus border color of root
root.invalidBorderColor	--p-treeselect-invalid-border-color	Invalid border color of root
root.color	--p-treeselect-color	Color of root
root.disabledColor	--p-treeselect-disabled-color	Disabled color of root
root.placeholderColor	--p-treeselect-placeholder-color	Placeholder color of root
root.invalidPlaceholderColor	--p-treeselect-invalid-placeholder-color	Invalid placeholder color of root
root.shadow	--p-treeselect-shadow	Shadow of root
root.paddingX	--p-treeselect-padding-x	Padding x of root
root.paddingY	--p-treeselect-padding-y	Padding y of root
root.borderRadius	--p-treeselect-border-radius	Border radius of root
focusRing.width	--p-treeselect-focus-ring-width	Focus ring width of root
focusRing.style	--p-treeselect-focus-ring-style	Focus ring style of root
focusRing.color	--p-treeselect-focus-ring-color	Focus ring color of root
focusRing.offset	--p-treeselect-focus-ring-offset	Focus ring offset of root
focusRing.shadow	--p-treeselect-focus-ring-shadow	Focus ring shadow of root
root.transitionDuration	--p-treeselect-transition-duration	Transition duration of root
sm.fontSize	--p-treeselect-sm-font-size	Sm font size of root
sm.paddingX	--p-treeselect-sm-padding-x	Sm padding x of root
sm.paddingY	--p-treeselect-sm-padding-y	Sm padding y of root
lg.fontSize	--p-treeselect-lg-font-size	Lg font size of root
lg.paddingX	--p-treeselect-lg-padding-x	Lg padding x of root
lg.paddingY	--p-treeselect-lg-padding-y	Lg padding y of root
dropdown.width	--p-treeselect-dropdown-width	Width of dropdown
dropdown.color	--p-treeselect-dropdown-color	Color of dropdown
overlay.background	--p-treeselect-overlay-background	Background of overlay
overlay.borderColor	--p-treeselect-overlay-border-color	Border color of overlay
overlay.borderRadius	--p-treeselect-overlay-border-radius	Border radius of overlay
overlay.color	--p-treeselect-overlay-color	Color of overlay
overlay.shadow	--p-treeselect-overlay-shadow	Shadow of overlay
tree.padding	--p-treeselect-tree-padding	Padding of tree
clearIcon.color	--p-treeselect-clear-icon-color	Color of clear icon
emptyMessage.padding	--p-treeselect-empty-message-padding	Padding of empty message
chip.borderRadius	--p-treeselect-chip-border-radius	Border radius of chip