Tree

Tree is used to display hierarchical data.

Import #


import { Tree } from 'primeng/tree';

Basic #

Tree component requires an array of TreeNode objects as its value.

Documents

Events

Movies


<p-tree [value]="files" styleClass="w-full md:w-[30rem]" />

Controlled #

Tree requires a collection of TreeNode instances as a value.

Documents

Events

Movies


<div class="flex flex-wrap gap-2 mb-6">
    <p-button icon="pi pi-plus" label="Expand all" (click)="expandAll()" />
    <p-button icon="pi pi-minus" label="Collapse all" (click)="collapseAll()" />
</div>
<p-tree [value]="files" styleClass="w-full md:w-[30rem]" />

Selection #

Single #

Single node selection is configured by setting selectionMode as single along with selection properties to manage the selection value binding.

Documents

Events

Movies


<p-tree [value]="files" styleClass="w-full md:w-[30rem]" selectionMode="single" [(selection)]="selectedFile" />

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, Tree 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.

MetaKey

Documents

Events

Movies


<div class="flex items-center mb-6 gap-2">
    <p-toggleswitch inputId="input-metakey" [(ngModel)]="metaKeySelection" />
    <label for="input-metakey">MetaKey</label>
</div>
<p-tree [metaKeySelection]="metaKeySelection" [value]="files" styleClass="w-full md:w-[30rem]" selectionMode="multiple" [(selection)]="selectedFiles" />

Checkbox #

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

Documents

Events

Movies


<p-tree [value]="files" selectionMode="checkbox" styleClass="w-full md:w-[30rem]" [(selection)]="selectedFiles" />

Events #

An event is provided for each type of user interaction such as expand, collapse and selection.

Documents

Events

Movies


<p-tree [value]="files" styleClass="w-full md:w-[30rem]" selectionMode="single" [(selection)]="selectedFile" (onNodeExpand)="nodeExpand($event)" (onNodeCollapse)="nodeCollapse($event)" (onNodeSelect)="nodeSelect($event)" (onNodeUnselect)="nodeUnselect($event)" />

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. Default value of loadingMode is mask and also icon is available.

Mask Mode

Node 0

Node 1

Node 2

Icon Mode

Node 0

Node 1

Node 2


<p-tree styleClass="w-full md:w-[30rem]" [value]="nodes" (onNodeExpand)="onNodeExpand($event)" [loading]="loading" />
<p-tree styleClass="w-full md:w-[30rem]" [value]="nodes2" loadingMode="icon" (onNodeExpand)="onNodeExpand2($event)" />

Template #

Custom node content instead of a node label is defined with the pTemplate property.

Introduction

Components In-Depth


<p-tree [value]="nodes" styleClass="w-full md:w-[30rem]">
    <ng-template let-node pTemplate="url">
        <a [href]="node.data" target="_blank" rel="noopener noreferrer" class="text-surface-700 dark:text-surface-100 hover:text-primary">
            {{ node.label }}
        </a>
    </ng-template>
    <ng-template let-node pTemplate="default">
        <b>{{ node.label }}</b>
    </ng-template>
</p-tree>

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.

Documents

Events

Movies

Documents

Events

Movies


<p-tree [value]="files" styleClass="w-full md:w-[30rem]" [filter]="true" filterPlaceholder="Lenient Filter" />
<p-tree [value]="files2" styleClass="w-full md:w-[30rem]" [filter]="true" filterMode="strict" filterPlaceholder="Strict Filter" />

Virtual Scroll #

Preload #

VirtualScroller is a performance-approach to handle huge data efficiently. Setting virtualScroll property as true and providing a virtualScrollItemSize in pixels would be enough to enable this functionality.


<p-tree [value]="files" styleClass="w-full md:w-[30rem]" scrollHeight="250px" [virtualScroll]="true" [virtualScrollItemSize]="46" />

Lazy #


<p-tree styleClass="w-full md:w-[30rem]" scrollHeight="250px" [virtualScroll]="true" [lazy]="true" [virtualScrollItemSize]="46" [value]="files" (onNodeExpand)="nodeExpand($event)" [loading]="loading" />

DragDrop #

Nodes can be reordered within the same tree and also can be transferred between other trees using drag&drop.

Documents

Events

Movies


<p-tree [value]="files" styleClass="w-full md:w-[30rem]" [draggableNodes]="true" [droppableNodes]="true" draggableScope="self" droppableScope="self" />

Context Menu #

Tree requires a collection of TreeNode instances as a value.

Documents

Events

Movies


<p-tree [value]="files" styleClass="w-full md:w-[30rem]" selectionMode="single" [(selection)]="selectedFile" [contextMenu]="cm" />
<p-contextmenu #cm [model]="items" />
<p-toast />

Accessibility #

Screen Reader

Value to describe the component can either be provided with aria-labelledby or aria-label props. The root list element has a tree role whereas 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. The container element of a treenode has the group role. 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 aria-setsize, aria-posinset and aria-level attributes are calculated implicitly and added to each treeitem.

Keyboard Support

Key	Function
tab	Moves focus to the first selected node when focus enters the component, if there is none then first element receives the focus. If focus is already inside the component, moves focus to the next focusable element in the page tab sequence.
shift + tab	Moves focus to the last selected node when focus enters the component, if there is none then first element receives the focus. If focus is already inside the component, moves focus to the previous focusable element in the page tab sequence.
enter	Selects the focused treenode.
space	Selects the focused treenode.
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.

name	type	default	description
value	any	null	An array of treenodes.
selectionMode	"multiple" \| "checkbox" \| "single"	null	Defines the selection mode.
loadingMode	"mask" \| "icon"	mask	Loading mode display.
selection	any	null	A single treenode instance or an array to refer to the selections.
style	Object	null	Inline style of the component.
styleClass	string	null	Style class of the component.
contextMenu	any	null	Context menu instance.
draggableScope	any	null	Scope of the draggable nodes to match a droppableScope.
droppableScope	any	null	Scope of the droppable nodes to match a draggableScope.
draggableNodes	boolean	false	Whether the nodes are draggable.
droppableNodes	boolean	false	Whether the nodes are droppable.
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.
propagateSelectionUp	boolean	true	Whether checkbox selections propagate to ancestor nodes.
propagateSelectionDown	boolean	true	Whether checkbox selections propagate to descendant nodes.
loading	boolean	false	Displays a loader to indicate data load is in progress.
loadingIcon	string	null	The icon to show while indicating data load is in progress.
emptyMessage	string	null	Text to display when there is no data.
ariaLabel	string	null	Used to define a string that labels the tree.
togglerAriaLabel	string	null	Defines a string that labels the toggler icon for accessibility.
ariaLabelledBy	string	null	Establishes relationships between the component and label(s) where its value should be one or more element IDs.
validateDrop	boolean	false	When enabled, drop can be accepted or rejected based on condition defined at onNodeDrop.
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.
filterOptions	any	null	Mode for filtering valid values are "lenient" and "strict". Default is lenient.
filterPlaceholder	string	null	Placeholder text to show when filter input is empty.
filteredNodes	TreeNode<any>[]	null	Values after the tree nodes are filtered.
filterLocale	string	null	Locale to use in filtering. The default locale is the host environment's current locale.
scrollHeight	string	null	Height of the scrollable viewport.
lazy	boolean	false	Defines if data is loaded and interacted with in lazy manner.
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.
indentation	number	1.5	Indentation factor for spacing of the nested node when virtual scrolling is enabled.
_templateMap	any	null	Custom templates of the component.
trackBy	Function	...	Function to optimize the node list rendering, default algorithm checks for object identity.
highlightOnSelect	boolean	false	Highlights the node on select.
_virtualNodeHeight	number	null	Height of the node.

name	parameters	description
selectionChange	value : TreeNode	Callback to invoke on selection change.
onNodeSelect	event : TreeNodeSelectEvent	Callback to invoke when a node is selected.
onNodeUnselect	event : TreeNodeUnSelectEvent	Callback to invoke when a node is unselected.
onNodeExpand	event : TreeNodeExpandEvent	Callback to invoke when a node is expanded.
onNodeCollapse	event : TreeNodeCollapseEvent	Callback to invoke when a node is collapsed.
onNodeContextMenuSelect	event : TreeNodeContextMenuSelectEvent	Callback to invoke when a node is selected with right click.
onNodeDrop	event : TreeNodeDropEvent	Callback to invoke when a node is dropped.
onLazyLoad	event : TreeLazyLoadEvent	Callback to invoke in lazy mode to load new data.
onScroll	event : TreeScrollEvent	Callback to invoke in virtual scroll mode when scroll position changes.
onScrollIndexChange	event : TreeScrollIndexChangeEvent	Callback to invoke in virtual scroll mode when scroll position and item's range in view changes.
onFilter	event : TreeFilterEvent	Callback to invoke when data is filtered.

name	parameters	description
resetFilter		Resets filter.
scrollToVirtualIndex	index : number	Scrolls to virtual index.
scrollTo	options : any	Scrolls to virtual index.

name	parameters	description
header		Custom header template.
empty		Custom empty message template.
footer		Custom footer template.
loader	context : { options: ScrollerOptions, // Scroller options. }	Custom loader template.
togglericon	context : { $implicit: boolean, // Expanded state of the node. }	Custom toggler icon template.
checkboxicon	context : { $implicit: boolean, // Checked state of the node. partialSelected: boolean, // Partial selection state of the node. }	Custom checkbox icon template.
loadingicon		Custom loading icon template.
filtericon		Custom filter icon template.

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

name	type	description
originalEvent	DragEvent	Browser drag event.
dragNode	TreeNode<any>	Dragged node instance.
dropNode	TreeNode<any>	Dropped node instance.
index	number	Index of the dragged node.
accept	Function	Callback to invoke on drop.

name	type	description
first	number	First element index in viewport.
last	number	Last element index in viewport.

name	type	description
filter	string	Filter value.
filteredValue	TreeNode<any>[]	Filtered nodes.

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-tree	Class name of the root element
p-tree-mask	Class name of the mask element
p-tree-loading-icon	Class name of the loading icon element
p-tree-filter-input	Class name of the filter input element
p-tree-root	Class name of the wrapper element
p-tree-root-children	Class name of the root children element
p-tree-node	Class name of the node element
p-tree-node-content	Class name of the node content element
p-tree-node-toggle-button	Class name of the node toggle button element
p-tree-node-toggle-icon	Class name of the node toggle icon element
p-tree-node-checkbox	Class name of the node checkbox element
p-tree-node-icon	Class name of the node icon element
p-tree-node-label	Class name of the node label element
p-tree-node-children	Class name of the node children element

token	variable	description
root.background	--p-tree-background	Background of root
root.color	--p-tree-color	Color of root
root.padding	--p-tree-padding	Padding of root
root.gap	--p-tree-gap	Gap of root
root.indent	--p-tree-indent	Indent of root
root.transitionDuration	--p-tree-transition-duration	Transition duration of root
node.padding	--p-tree-node-padding	Padding of node
node.borderRadius	--p-tree-node-border-radius	Border radius of node
node.hoverBackground	--p-tree-node-hover-background	Hover background of node
node.selectedBackground	--p-tree-node-selected-background	Selected background of node
node.color	--p-tree-node-color	Color of node
node.hoverColor	--p-tree-node-hover-color	Hover color of node
node.selectedColor	--p-tree-node-selected-color	Selected color of node
focusRing.width	--p-tree-node-focus-ring-width	Focus ring width of node
focusRing.style	--p-tree-node-focus-ring-style	Focus ring style of node
focusRing.color	--p-tree-node-focus-ring-color	Focus ring color of node
focusRing.offset	--p-tree-node-focus-ring-offset	Focus ring offset of node
focusRing.shadow	--p-tree-node-focus-ring-shadow	Focus ring shadow of node
node.gap	--p-tree-node-gap	Gap of node
nodeIcon.color	--p-tree-node-icon-color	Color of node icon
nodeIcon.hoverColor	--p-tree-node-icon-hover-color	Hover color of node icon
nodeIcon.selectedColor	--p-tree-node-icon-selected-color	Selected color of node icon
nodeToggleButton.borderRadius	--p-tree-node-toggle-button-border-radius	Border radius of node toggle button
nodeToggleButton.size	--p-tree-node-toggle-button-size	Size of node toggle button
nodeToggleButton.hoverBackground	--p-tree-node-toggle-button-hover-background	Hover background of node toggle button
nodeToggleButton.selectedHoverBackground	--p-tree-node-toggle-button-selected-hover-background	Selected hover background of node toggle button
nodeToggleButton.color	--p-tree-node-toggle-button-color	Color of node toggle button
nodeToggleButton.hoverColor	--p-tree-node-toggle-button-hover-color	Hover color of node toggle button
nodeToggleButton.selectedHoverColor	--p-tree-node-toggle-button-selected-hover-color	Selected hover color of node toggle button
focusRing.width	--p-tree-node-toggle-button-focus-ring-width	Focus ring width of node toggle button
focusRing.style	--p-tree-node-toggle-button-focus-ring-style	Focus ring style of node toggle button
focusRing.color	--p-tree-node-toggle-button-focus-ring-color	Focus ring color of node toggle button
focusRing.offset	--p-tree-node-toggle-button-focus-ring-offset	Focus ring offset of node toggle button
focusRing.shadow	--p-tree-node-toggle-button-focus-ring-shadow	Focus ring shadow of node toggle button
loadingIcon.size	--p-tree-loading-icon-size	Size of loading icon

Tree

Import #

Basic #

Controlled #

Selection #

Single #

Multiple #

Checkbox #

Events #

Lazy #

Template #

Filter #

Virtual Scroll #

Preload #

Lazy #

DragDrop #

Context Menu #

Accessibility #

Screen Reader

Keyboard Support

Tree API

Tree #

Properties #

Emitters #

Methods #

Templates #

Events #

TreeNodeSelectEvent #

TreeNodeUnSelectEvent #

TreeNodeExpandEvent #

TreeNodeCollapseEvent #

TreeNodeContextMenuSelectEvent #

TreeNodeDropEvent #

TreeLazyLoadEvent #

TreeScrollIndexChangeEvent #

TreeScrollEvent #

TreeFilterEvent #

Interfaces #

TreeNode #

Tree Theming

CSS Classes #

Tree Design Tokens #