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

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

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

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

Float Label #

A floating label appears on top of the input field when focused.

Select Item

TreeSelect


<span class="p-float-label md:w-20rem w-full">
    <p-treeSelect containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" placeholder="Select Item"></p-treeSelect>
    <label for="treeselect">TreeSelect</label>
</span>

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

Disabled #

When disabled is present, the element cannot be edited and focused.

Select Item


<p-treeSelect class="md:w-20rem w-full" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" [disabled]="true" placeholder="Select Item"></p-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>

<p-treeSelect ariaLabel="Options"></p-treeSelect>

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

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	value : any	Callback to invoke when data is filtered.
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	null	Custom empty template.
footer	null	Custom footer template.
clearicon	null	Custom clear icon template.
triggericon	null	Custom dropdown trigger icon template.
filtericon	null	Custom filter icon template.
closeicon	null	Custom close icon template.
itemtogglericon	context : { $implicit: boolean, // Expanded state of the node. }	Custom node toggler template.
itemcheckboxicon	null	Custom node checkbox icon template.
itemloadingicon	null	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
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.