techno-vue-treeselect
A multi-select component with nested options support for Vue.js
Features
- Single & multiple select with nested options support
- Fuzzy matching
- Async searching
- Delayed loading (load data of deep level options only when needed)
- Keyboard support (navigate using Arrow Up & Arrow Down keys, select option using Enter key, etc.)
- Rich options & highly customizable
- Supports a wide range of browsers (see below)
- RTL support
Requires Vue 2.2+
Getting Started
It's recommended to install vue-treeselect via npm, and build your app using a bundler like webpack.
npm install @mail2gowthamganesan/techno-vue-treeselect
This example shows how to integrate vue-treeselect with your Vue SFCs.
<!-- Vue SFC -->
<template>
<div id="app">
<treeselect v-model="value" :multiple="true" :options="options" />
</div>
</template>
<script>
// import the component
import Treeselect from '@mail2gowthamganesan/vue-treeselect'
// import the styles
import '@mail2gowthamganesan/vue-treeselect/dist/vue-treeselect.css'
export default {
// register the component
components: { Treeselect },
data() {
return {
// define the default value
value: null,
// define options
options: [ {
id: 'a',
label: 'a',
// control checkbox show/hide
checkBox: false,
children: [ {
id: 'aa',
label: 'aa',
}, {
id: 'ab',
label: 'ab',
} ],
}, {
id: 'b',
label: 'b',
}, {
id: 'c',
label: 'c',
} ],
}
},
}
</script>
Props
Name | Type / Default | Description |
---|---|---|
allowClearingDisabled |
Type: Boolean Default: false
|
Whether to allow resetting value even if there are disabled selected nodes. |
allowSelectingDisabledDescendants |
Type: Boolean Default: false
|
When an ancestor node is selected/deselected, whether its disabled descendants should be selected/deselected. You may want to use this in conjunction with allowClearingDisabled prop. |
alwaysOpen |
Type: Boolean Default: false
|
Whether the menu should be always open. |
appendToBody |
Type: Boolean Default: false
|
Append the menu to <body /> . |
async |
Type: Boolean Default: false
|
Whether to enable async search mode. |
autoFocus |
Type: Boolean Default: false
|
Automatically focus the component on mount. |
autoLoadRootOptions |
Type: Boolean Default: true
|
Automatically load root options on mount. When set to false , root options will be loaded when the menu is opened. |
autoDeselectAncestors |
Type: Boolean Default: false
|
When user deselects a node, automatically deselect its ancestors. Applies to flat mode only. |
autoDeselectDescendants |
Type: Boolean Default: false
|
When user deselects a node, automatically deselect its descendants. Applies to flat mode only. |
autoSelectAncestors |
Type: Boolean Default: false
|
When user selects a node, automatically select its ancestors. Applies to flat mode only. |
autoSelectDescendants |
Type: Boolean Default: false
|
When user selects a node, automatically select its descendants. Applies to flat mode only. |
backspaceRemoves |
Type: Boolean Default: true
|
Whether Backspace removes the last item if there is no text input. |
beforeClearAll |
Type: Fn() 🡒 (Boolean | Promise) Default: () => true
|
Function that processes before clearing all input fields. Return false to stop values being cleared. |
branchNodesFirst |
Type: Boolean Default: false
|
Show branch nodes before leaf nodes. |
cacheOptions |
Type: Boolean Default: true
|
Whether to cache results of each search request for async search mode. |
clearable |
Type: Boolean Default: true
|
Whether to show an "×" button that resets value. |
clearAllText |
Type: String Default:"Clear all"
|
Title for the "×" button when :multiple="true" . |
clearOnSelect |
Type: Boolean Default: Defaults to false when :multiple="true" ; always true otherwise. |
Whether to clear the search input after selecting an option. Use only when :multiple="true" . For single-select mode, it always clears the input after selecting regardless of the prop value. |
clearValueText |
Type: String Default:"Clear value"
|
Title for the "×" button. |
closeOnSelect |
Type: Boolean Default: true
|
Whether to close the menu after selecting an option. Use only when :multiple="true" . |
defaultExpandLevel |
Type: Number Default: 0
|
How many levels of branch nodes should be automatically expanded when loaded. Set Infinity to make all branch nodes expanded by default. |
defaultOptions | Type: Boolean |
node[] Default: false
|
deleteRemoves |
Type: Boolean Default: true
|
Whether Delete removes the last item if there is no text input. |
delimiter |
Type: String Default:","
|
Delimiter to use to join multiple values for the hidden field value. |
flattenSearchResults |
Type: Boolean Default: false
|
Whether to flatten the tree when searching (sync search mode only). See here for example. |
disableBranchNodes |
Type: Boolean Default: false
|
Whether to prevent branch nodes from being selected. See here for example. |
disabled |
Type: Boolean Default: false
|
Whether to disable the control or not. |
disableFuzzyMatching |
Type: Boolean Default: false
|
Set to true to disable the fuzzy matching functionality, which is enabled by default. |
flat |
Type: Boolean Default: false
|
Whether to enable flat mode or not. See here for detailed information. |
instanceId | Type: String | Number Default: "<auto-incrementing number>$$"
|
joinValues |
Type: Boolean Default: false
|
Joins multiple values into a single form field with the delimiter (legacy mode). |
limit |
Type: Number Default: Infinity
|
Limit the display of selected options. The rest will be hidden within the limitText string. |
limitText |
Type: Fn(count ) 🡒 String Default: ``count => `and ${count} more``` |
Function that processes the message shown when selected elements pass the defined limit. |
loadingText |
Type: String Default: "Loading..."
|
Text displayed when loading options. |
loadOptions |
Type: Fn({action , callback , parentNode? , instanceId }) 🡒 (void
|
Promise) Default:– |
matchKeys |
Type: String[] Default: [ "label" ]
|
Which keys of a node object to filter on. |
maxHeight |
Type: Number Default: 300
|
Sets maxHeight style value of the menu. |
multiple |
Type: Boolean Default: false
|
Set true to allow selecting multiple options (a.k.a., multi-select mode). |
name | Type: String Default:– | Generates a hidden <input /> tag with this field name for html forms. |
noChildrenText |
Type: String Default: "No sub-options."
|
Text displayed when a branch node has no children. |
noOptionsText |
Type: String Default: "No options available."
|
Text displayed when there are no available options. |
noResultsText |
Type: String Default: "No results found..."
|
Text displayed when there are no matching search results. |
normalizer |
Type: Fn(node , instanceId ) 🡒 node Default: node => node
|
Used for normalizing source data. See here for detailed information. |
openDirection |
Type: String Default: "auto"
|
By default ("auto" ), the menu will open below the control. If there is not enough space, vue-treeselect will automatically flip the menu. You can use one of other four options to force the menu to be always opened to specified direction. Acceptable values: "auto" , "below" , "bottom" , "above" or "top" . |
openOnClick |
Type: Boolean Default: true
|
Whether to automatically open the menu when the control is clicked. |
openOnFocus |
Type: Boolean Default: false
|
Whether to automatically open the menu when the control is focused. |
options |
Type: node[] Default:– |
Array of available options. See here to learn how to define them. |
placeholder |
Type: String Default: "Select..."
|
Field placeholder, displayed when there's no value. |
required |
Type: Boolean Default: false
|
Applies HTML5 required attribute when needed. |
retryText |
Type: String Default: "Retry?"
|
Text displayed asking user whether to retry loading children options. |
retryTitle |
Type: String Default: "Click to retry"
|
Title for the retry button. |
searchable | **Type:**Boolean Default: true
|
Whether to enable searching feature or not. |
searchNested |
Type: Boolean Default: false
|
Set true if the search query should search in all ancestor nodes too. See here for example. |
searchPromptText |
Type: String Default: "Type to search..."
|
Text tip to prompt for async search. Used for async search mode. |
showCount |
Type: Boolean Default: false
|
Whether to show a children count next to the label of each branch node. See here for example. |
showCountOf |
Type: String Default: "ALL_CHILDREN"
|
Used in conjunction with showCount to specify which type of count number should be displayed. Acceptable values: "ALL_CHILDREN" , "ALL_DESCENDANTS" , "LEAF_CHILDREN" or "LEAF_DESCENDANTS" . |
showCountOnSearch | Type: Boolean Default:– | Whether to show children count when searching. Fallbacks to the value of showCount when not specified. |
sortValueBy |
Type: String Default: "ORDER_SELECTED"
|
In which order the selected options should be displayed in trigger & sorted in value array. Use only when :multiple="true" . See here for example. Acceptable values: "ORDER_SELECTED" , "LEVEL" or "INDEX" . |
tabIndex |
Type: Number Default: 0
|
Tab index of the control. |
value |
Type: id |node |id[] |node[] Default:– |
The value of the control. Should be id or node object when :multiple="false" , or an array of id or node object when :multiple="true" . Its format depends on the valueFormat prop. For most cases, just use v-model instead. |
valueConsistsOf |
Type: String Default:"BRANCH_PRIORITY"
|
Which kind of nodes should be included in the value array in multi-select mode. See here for example. Acceptable values: "ALL" , "BRANCH_PRIORITY" , "LEAF_PRIORITY" , "SECOND_LEAF_PRIORITY" or "ALL_WITH_INDETERMINATE" . |
valueFormat |
Type: String Default:"id"
|
Format of value prop. Note that, when set to "object" , only id & label properties are required in each node object in value . Acceptable values: "id" or "object" . |
zIndex |
Type: Number | String Default: 999
|
z-index of the menu. |
showTooTip |
Type: Boolean Default: false
|
Whether to show Tooltip. |
Documentation & Live Demo
Note: please use a desktop browser since the website hasn't been optimized for mobile devices.
Browser Compatibility
- Chrome
- Edge
- Firefox
- IE ≥ 9
- Safari
It should function well on IE9, but the style can be slightly broken due to the lack of support of some relatively new CSS features, such as transition
and animation
. Nevertheless it should look 90% same as on modern browsers.
Contributing
- Fork & clone the repo
- Install dependencies by
yarn
ornpm install
- Check out a new branch
-
npm run dev
& hack - Make sure
npm test
passes - Push your changes & file a pull request