import TreeSelect from 'primevue/treeselect';
<script src="https://unpkg.com/primevue@^3/core/core.min.js"></script>
<script src="https://unpkg.com/primevue@^3/treeselect/treeselect.min.js"></script>
TreeSelect component requires an array of TreeNode objects as its options and keys of the nodes as its value.
<TreeSelect v-model="selectedNodeKey" :options="nodes" placeholder="Select Item" />
In example below, nodes are retrieved from a remote data source.
import NodeService from '../../service/NodeService';
export default {
data() {
return {
selectedNodeKey: null,
nodes: null
}
},
nodeService: null,
created() {
this.nodeService = new NodeService();
},
mounted() {
this.nodeService.getTreeNodes().then(data => this.nodes = data);
}
}
export default class NodeService {
getTreeNodes() {
return fetch('demo/data/treenodes.json').then(res => res.json())
.then(d => d.root);
}
}
The json response sample would be as following.
{
"root": [
{
"key": "0",
"label": "Documents",
"data": "Documents Folder",
"icon": "pi pi-fw pi-inbox",
"children": [{
"key": "0-0",
"label": "Work",
"data": "Work Folder",
"icon": "pi pi-fw pi-cog",
"children": [{ "key": "0-0-0", "label": "Expenses.doc", "icon": "pi pi-fw pi-file", "data": "Expenses Document" }, { "key": "0-0-1", "label": "Resume.doc", "icon": "pi pi-fw pi-file", "data": "Resume Document" }]
},
{
"key": "0-1",
"label": "Home",
"data": "Home Folder",
"icon": "pi pi-fw pi-home",
"children": [{ "key": "0-1-0", "label": "Invoices.txt", "icon": "pi pi-fw pi-file", "data": "Invoices for this month" }]
}]
},
{
"key": "1",
"label": "Events",
"data": "Events Folder",
"icon": "pi pi-fw pi-calendar",
"children": [
{ "key": "1-0", "label": "Meeting", "icon": "pi pi-fw pi-calendar-plus", "data": "Meeting" },
{ "key": "1-1", "label": "Product Launch", "icon": "pi pi-fw pi-calendar-plus", "data": "Product Launch" },
{ "key": "1-2", "label": "Report Review", "icon": "pi pi-fw pi-calendar-plus", "data": "Report Review" }]
},
{
"key": "2",
"label": "Movies",
"data": "Movies Folder",
"icon": "pi pi-fw pi-star-fill",
"children": [{
"key": "2-0",
"icon": "pi pi-fw pi-star-fill",
"label": "Al Pacino",
"data": "Pacino Movies",
"children": [{ "key": "2-0-0", "label": "Scarface", "icon": "pi pi-fw pi-video", "data": "Scarface Movie" }, { "key": "2-0-1", "label": "Serpico", "icon": "pi pi-fw pi-video", "data": "Serpico Movie" }]
},
{
"key": "2-1",
"label": "Robert De Niro",
"icon": "pi pi-fw pi-star-fill",
"data": "De Niro Movies",
"children": [{ "key": "2-1-0", "label": "Goodfellas", "icon": "pi pi-fw pi-video", "data": "Goodfellas Movie" }, { "key": "2-1-1", "label": "Untouchables", "icon": "pi pi-fw pi-video", "data": "Untouchables Movie" }]
}]
}
]
}
| Name | Type | Default | Description |
|---|---|---|---|
| key | any | null | Mandatory unique key of the node. |
| label | string | null | Label of the node. |
| data | any | null | Data represented by the node. |
| type | string | null | Type of the node to match a template. |
| icon | string | null | Icon of the node to display next to content. |
| children | TreeNode[] | null | An array of treenodes as children. |
| style | string | null | Inline style of the node. |
| styleClass | string | null | Style class of the node. |
| selectable | boolean | null | Whether the node is selectable when selection mode is enabled. |
| leaf | boolean | null | Specifies if the node has children. Used in lazy loading. |
TreeSelects offers "single", "multiple" and "checkbox" alternatives for the selection behavior that is defined by the selectionMode option.
<TreeSelect v-model="selectedValue1" :options="nodes" selectionMode="single" placeholder="Select Item" />
<TreeSelect v-model="selectedValue2" :options="nodes" selectionMode="multiple" placeholder="Select Items" />
<TreeSelect v-model="selectedValue3" :options="nodes" selectionMode="checkbox" placeholder="Select Items" />
Value passed to and from the TreeSelect via the v-model directive should be a an object with key-value pairs where key is the node key and value is a boolean to indicate selection. On the other hand in "checkbox" mode, instead of a boolean, value should be an object that has "checked" and "partialChecked" properties to represent the checked state of a node. Best way to clarify it is prepopulating a TreeSelect with an existing value.
data() {
return {
selectedValue1: {'2-1': true},
selectedValue2: {'1-1': true, '0-0-0': true},
selectedValue2: {'1': {checked: true, partialChecked: true}, '1-0': {checked: true}}
nodes: null
}
},
A comma separated list is used by default to display selected items whereas alternative chip mode is provided using the display property to visualize the items as tokens.
<TreeSelect v-model="selectedValue" display="chip" :options="nodes" selectionMode="multiple" placeholder="Select Items" />
Label of an option is used as the display text of an item by default, for custom content support define a value template that gets the selected nodes as a parameter. In addition header, footer and empty slots are provided for further customization.
<TreeSelect v-model="selectedNodes" :options="nodes" placeholder="Select Items">
<template #value="{value}">
Custom Content
</template>
</TreeSelect>
Any property as style and class are passed to the main container element. Following are the additional properties to configure the component.
| Name | Type | Default | Description |
|---|---|---|---|
| modelValue | any | null | Value of the component. |
| options | array | null | An array of treenodes. |
| scrollHeight | string | 200px | 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. |
| selectionMode | string | null | Defines the selection mode, valid values "single", "multiple", and "checkbox". |
| 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 PrimeVue locale configuration. |
| display | string | comma | Defines how the selected items are displayed, valid values are "comma" and "chip". |
| 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. |
| inputId | string | null | Identifier of the underlying input element. |
| inputClass | string | null | Style class of the input field. |
| inputStyle | any | null | Inline style of the input field. |
| panelClass | string | null | Style class of the overlay panel. |
| Name | Parameters | Description |
|---|---|---|
| change | event: Selected node keys | Callback to invoke on value change. |
| before-show | - | Callback to invoke before the overlay is shown. |
| before-hide | - | Callback to invoke before the overlay is hidden. |
| show | - | Callback to invoke when the overlay is shown. |
| hide | - | Callback to invoke when the overlay is hidden. |
| node-select | node: Node instance | Callback to invoke when a node is selected. |
| node-unselect | node: Node instance | Callback to invoke when a node is unselected. |
| node-expand | node: Node instance | Callback to invoke when a node is expanded. |
| node-collapse | node: Node instance | Callback to invoke when a node is collapsed. |
| Name | Parameters | Description |
|---|---|---|
| show | - | Shows the overlay. |
| hide | - | Hides the overlay. |
| Name | Parameters |
|---|---|
| value |
value: Selected nodes placeholder: Placeholder value |
| header |
value: Value of the component options: TreeNode options |
| footer |
value: Value of the component options: TreeNode options |
| empty | - |
| indicator | - |
Following is the list of structural style classes, for theming classes visit
| 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.
<span id="dd1">Options</span>
<TreeSelect aria-labelledby="dd1" />
<TreeSelect aria-label="Options" />
| 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 page tab sequence. |
| shift + tab | Moves focus to the previous focusable element in the page tab sequence. |
| 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. |
None.