TreeSelect is a form component to choose from hierarchical data.
import { TreeSelectModule } from 'primeng/treeselect';
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.
<p-treeSelect class="md:w-20rem w-full" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" placeholder="Select Item"></p-treeSelect>
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>
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
}
<p-treeSelect class="w-full md:w-20rem" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" [metaKeySelection]="false" selectionMode="multiple" placeholder="Select Item"></p-treeSelect>
Selection of multiple nodes via checkboxes is enabled by configuring selectionMode as checkbox.
<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>
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-treeSelect class="md:w-20rem w-full" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" placeholder="Select Item" [filter]="true" [filterInputAutoFocus]="true"></p-treeSelect>
A floating label appears on top of the input field when focused.
<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 state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.
<p-treeSelect class="md:w-20rem w-full ng-invalid ng-dirty" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" placeholder="Select Item"></p-treeSelect>
When disabled is present, the element cannot be edited and focused.
<p-treeSelect class="md:w-20rem w-full" containerStyleClass="w-full" [(ngModel)]="selectedNodes" [options]="nodes" [disabled]="true" placeholder="Select Item"></p-treeSelect>
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. |
Value to describe the component can either be provided with aria-labelledby or aria-label 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 aria-labelledby="dd1"></p-treeSelect>
<p-treeSelect aria-label="Options"></p-treeSelect>
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. |
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. |
Key | Function |
---|---|
enter | Closes the popup and moves focus to the treeselect element. |
escape | Closes the popup and moves focus to the treeselect element. |
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. |
API defines helper props, events and others for the PrimeNG TreeSelect module.
Name | Type | Default | Description |
---|---|---|---|
options | array | null | An array of treenodes. |
scrollHeight | string | 400px | Height of the viewport, a scrollbar is defined if height of list exceeds this value. |
placeholder | string | null | Label to display when there are no selections. |
disabled | boolean | false | When present, it specifies that the component should be disabled. |
tabindex | string | null | Index of the element in tabbing order. |
inputId | string | null | Identifier of the underlying input element. |
ariaLabelledBy | string | null | Establishes relationships between the component and label(s) where its value should be one or more element IDs. |
selectionMode | string | null | Defines the selection mode, valid values "single", "multiple", and "checkbox". |
panelClass | string | null | Style class of the overlay panel. |
appendTo | string | body | 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. |
emptyMessage | string | No results found | Text to display when there are no options available. Defaults to value from PrimeNG locale configuration. |
display | string | comma | Defines how the selected items are displayed, valid values are "comma" and "chip". |
propagateSelectionUp | boolean | true | Whether checkbox selections propagate to ancestor nodes. |
propagateSelectionDown | boolean | true | Whether checkbox selections propagate to descendant nodes. |
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. |
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. |
resetFilterOnHide | boolean | true | Clears the filter value when hiding the dropdown. |
showClear | boolean | false | When enabled, a clear icon is displayed to clear the value. |
Name | Parameters | Description |
---|---|---|
onShow | - | Callback to invoke when the overlay is shown. |
onHide | - | Callback to invoke when the overlay is hidden. |
onFilter | event.filter: Filter value used in filtering. event.filteredValue: Filtered data after running the filtering. | Callback to invoke when data is filtered. |
onNodeSelect | node: Node instance | Callback to invoke when a node is selected. |
onNodeUnselect | node: Node instance | Callback to invoke when a node is unselected. |
onNodeExpand | node: Node instance | Callback to invoke when a node is expanded. |
onNodeCollapse | node: Node instance | Callback to invoke when a node is collapsed. |
onClear | - | Callback to invoke when input field is cleared. |
Name | Parameters |
---|---|
value | $implicit: Value of the component |
header | $implicit: Value of the component options: TreeNode options |
footer | $implicit: Value of the component options: TreeNode options |
empty | - |
clearicon | - |
triggericon | - |
filtericon | - |
closeicon | - |
itemtogglericon | $implicit: Expanded state of tree node. |
itemcheckboxicon | $implicit: Selected state. partialSelected: Whether the node is partial selected or not. |
itemloadingicon | - |