Tree is used to display hierarchical data.
import { TreeModule } from 'primeng/tree';
Tree component requires an array of TreeNode objects as its value.
<p-tree class="w-full md:w-30rem" [value]="files"></p-tree>
Tree requires a collection of TreeNode instances as a value.
<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>
Single node selection is configured by setting selectionMode as single along with selection properties to manage the selection value binding.
<p-tree [value]="files" class="w-full md:w-30rem" selectionMode="single" [(selection)]="selectedFile"></p-tree>
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.
<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>
Selection of multiple nodes via checkboxes is enabled by configuring selectionMode as checkbox.
<p-tree [value]="files" selectionMode="checkbox" class="w-full md:w-30rem" [(selection)]="selectedFiles"></p-tree>
An event is provided for each type of user interaction such as expand, collapse and selection.
<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 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>
Custom node content instead of a node label is defined with the pTemplate property.
<p-tree [value]="nodes" class="w-full md:w-30rem">
<ng-template let-node pTemplate="url">
<a [href]="node.data" target="_blank">{{ node.label }}</a>
</ng-template>
<ng-template let-node pTemplate="default">
<b>{{ node.label }}</b>
</ng-template>
</p-tree>
Nodes can be reordered within the same tree and also can be transferred between other trees using drag&drop.
<p-tree class="w-full md:w-30rem" [value]="files" [draggableNodes]="true" [droppableNodes]="true" draggableScope="self" droppableScope="self"></p-tree>
Tree requires a collection of TreeNode instances as a value.
<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>
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.
<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>
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 |
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.
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. |
API defines helper props, events and others for the PrimeNG Tree module.
Name | Type | Default | Description |
---|---|---|---|
value | array | null | An array of treenodes. |
selectionMode | string | null | Defines the selection mode, valid values "single", "multiple", and "checkbox". |
selection | any | null | A single treenode instance or an array to refer to the selections. |
style | string | null | Inline style of the component. |
styleClass | string | null | Style class of the component. |
contextMenu | ContextMenu | null | Context menu instance. |
layout | string | vertical | Defines the orientation of the tree, valid values are 'vertical' and 'horizontal'. |
draggableScope | string/array | null | Scope of the draggable nodes to match a droppableScope. |
droppableScope | string/array | 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 | No records found | Text to display when there is no data. |
ariaLabel | string | Used to define a string that labels the tree. | |
ariaLabelledBy | string | null | Establishes relationships between the component and label(s) where its value should be one or more element IDs. |
togglerAriaLabel | string | Defines a string that labels the toggler icon for accessibility. | |
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. |
filterLocale | string | undefined | Locale to use in filtering. The default locale is the host environment's current locale. |
scrollHeight | string | null | Height of the scrollable viewport. |
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. |
lazy | boolean | false | Defines if data is loaded and interacted with in lazy manner. |
trackBy | Function | null | Function to optimize the node list rendering, default algorithm checks for object identity. |
indentation | number | 1.5 | Indentation factor for spacing of the nested node when virtual scrolling is enabled. |
Name | Parameters | Description |
---|---|---|
onNodeSelect | event.originalEvent: browser event event.node: Selected node instance. | Callback to invoke when a node is selected. |
onNodeUnselect | event.originalEvent: browser event event.node: Unselected node instance. | Callback to invoke when a node is unselected. |
onNodeExpand | event.originalEvent: browser event event.node: Expanded node instance. | Callback to invoke when a node is expanded. |
onNodeCollapse | event.originalEvent: browser event event.node: Collapsed node instance. | Callback to invoke when a node is collapsed. |
onNodeContextMenuSelect | event.originalEvent: browser event event.node: Selected node instance. | Callback to invoke when a node is selected with right click. |
onNodeDrop | event.originalEvent: browser event event.dragNode: Dragged node instance event.dropNode: Dropped node instance. event.index: Index of the dropped node within siblings. | Callback to invoke when a node is dropped. |
onFilter | event.filter: Filter value used in filtering. event.filteredValue: Filtered data after running the filtering. | Callback to invoke when data is filtered. |
onLazyLoad | event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. | Callback to invoke in lazy mode to load new data. |
onScroll | event: Browser event | Callback to invoke in virtual scroll mode when scroll position changes. |
onScrollIndexChange | event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. | Callback to invoke in virtual scroll mode when scroll position and item's range in view changes. |
Name | Parameters | Description |
---|---|---|
resetFilter | - | Resets filtering. |
_filter | value: string | Applies filter by given value. |
scrollToVirtualIndex | index | Scrolls to the node with the given index when virtual scrolling is enabled. |
scrollTo | options.left: Specifies the number of pixels along the X axis options.top: Specifies the number of pixels along the Y axis options.behavior: Specifies whether the scrolling should animate smoothly (smooth), or happen instantly in a single jump (auto). | Scrolls to a position of a scrollable tree viewport. |
Name | Parameters |
---|---|
header | - |
empty | - |
footer | - |
loader | options: Options of the scroller on loading. *This template can be used with virtualScroll. |
togglericon | $implicit: Expanded state of tree node. |
checkboxicon | $implicit: Selected state. partialSelected: Whether the node is partial selected or not. |
loadingicon | - |
filtericon | - |