Tree

Tree is used to display hierarchical data.

Import #


import { TreeModule } from 'primeng/tree';

Basic #

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

Documents 2

Events 3

Movies 2


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

Controlled #

Tree requires a collection of TreeNode instances as a value.

Documents 2

Events 3

Movies 2


<div class="mb-3">
    <button pButton type="button" label="Expand all" (click)="expandAll()" class="mr-2"></button>
    <button pButton type="button" label="Collapse all" (click)="collapseAll()"></button>
</div>
<p-tree [value]="files" class="w-full md:w-30rem"></p-tree>

Selection #

Single #

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

Documents 2

Events 3

Movies 2


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

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 2

Events 3

Movies 2


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

Checkbox #

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

Documents 2

Events 3

Movies 2


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

Events #

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

Documents 2

Events 3

Movies 2


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

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.


<p-tree class="w-full md:w-30rem" [value]="files" (onNodeExpand)="nodeExpand($event)" [loading]="loading"></p-tree>

Template #

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

Introduction

Components In-Depth


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

DragDrop #

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

Documents 2

Events 3

Movies 2


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

Context Menu #

Tree requires a collection of TreeNode instances as a value.

Documents 2

Events 3

Movies 2


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

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 2

Events 3

Movies 2

Documents 2

Events 3

Movies 2


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

Style #

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

Name	Element
p-tree	Main container element
p-tree-horizontal	Main container element in horizontal mode
p-tree-container	Container of nodes
p-treenode	A treenode element
p-treenode-content	Content of a treenode
p-treenode-toggler	Toggle icon
p-treenode-icon	Icon of a treenode
p-treenode-label	Label of a treenode
p-treenode-children	Container element for node children

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.

Tree API

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

Tree #

Tree is used to display hierarchical data.

Properties #

Defines the input properties of the component.

name	type	default	description
value	any	null	An array of treenodes.
selectionMode	"multiple" \| "checkbox" \| "single"	null	Defines the selection mode.
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.
layout	string	vertical	Defines the orientation of the tree, valid values are 'vertical' and 'horizontal'.
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	true	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.
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.
_virtualNodeHeight	number	null	Height of the node.

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

Methods #

Defines methods that can be accessed by the component's reference.

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

Templates #

Defines the templates used by the component.

name	parameters	description
header	null	Custom header template.
empty	null	Custom empty message template.
footer	null	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	null	Custom loading icon template.
filtericon	null	Custom filter icon template.

Events #

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

TreeNodeSelectEvent #

Custom node select event.

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

TreeNodeUnSelectEvent #

Custom node unselect event.

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

TreeNodeExpandEvent #

Custom node expand event.

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

TreeNodeCollapseEvent #

Custom node collapse event.

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

TreeNodeContextMenuSelectEvent #

Custom context menu select event.

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

TreeNodeDropEvent #

Custom node drop event.

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.

TreeLazyLoadEvent #

Custom lazy load event.

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

TreeScrollIndexChangeEvent #

Custom scroll index change event.

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

TreeScrollEvent #

Custom scroll event.

name	type	description
originalEvent	Event	Browser event.

TreeFilterEvent #

Custom filter event.

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

Interfaces #

Defines the custom interfaces used by the module.

TreeNode #

Represents a node in a tree data structure.

name	type	description
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.