[](https://www.npmjs.com/package/@night-owl-elite/vue-select)
npm install @night-owl-elite/vue-select'text' or as 'chips'.
'checkbox' UI or a simple 'highlight' on click.
['name', 'user.email']) via keyFilters.
multiple: true).
allowAddNew prop).
#default slot to render each tree item.
#display slot to completely* customize the trigger/button area.
isLoading and disabled props.
selectAll, disableBranchNodes, and size variants (sm, md, lg, xl).
bash
npm install @night-owl-elite/vue-select
`
Props
| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| modelValue | [String, Number, Array] | null | The selected value(s). Use v-model. |
| items | Array | [] | The array of tree nodes to display. |
| multiple | Boolean | false | Allow multiple items to be selected. |
| displayMode | String | 'text' | How to display the selection: 'text' or 'chips'. |
| selectMode | String | 'checkbox' | UI style for selection: 'checkbox' or 'highlight'. |
| optionLabel | String | 'value' | The key in your item object to use for the display label. |
| optionValue | String | 'code' | The key in your item object to use for the unique value. |
| keyFilters | Array | [] | Array of keys to search against. E.g., ['name', 'details.email']. Defaults to optionLabel if empty. |
| placeholder | String | 'Select item...' | Placeholder text when no item is selected. |
| isInvalid | Boolean | false | Applies a visual "invalid" state (e.g., red border). |
| disabled | Boolean | false | Disables the entire component. |
| searchable | Boolean | true | Shows a search input in the dropdown. |
| isLoading | Boolean | false | Shows a loading state and disables the component. |
| showClearButton | Boolean | true | Shows a global "clear" (X) icon. |
| selectAll | Boolean | false | When true, selecting a parent node also selects all its children. |
| deselectAll | Boolean | true | When true, deselecting a parent node also deselects all its children. |
| canDeselect | Boolean | true | (Single select) Allows deselecting the active item. |
| disabledKey | String | null | The key in your item object to check if an item is disabled. |
| excludeFromSelectedListKey | String | null | Key to check if an item should be excluded from modelValue (e.g., for non-selectable parent groups). |
| disableBranchNodes | Boolean | false | Prevents selection of items that have children (branch nodes). |
| size | String | 'sm' | Component size: 'sm', 'md', 'lg', or 'xl'. |
| sortable | Boolean | false | Enables sorting controls in the dropdown. |
| sortOptions | Array | [] | Array of sort options. E.g., [{ value: 'name', label: 'Name' }]. |
| defaultSortKey | String | null | The default key (from sortOptions) to sort by. |
| defaultSortDirection | String | 'asc' | Default sort direction: 'asc' or 'desc'. |
| maxVisibleChipsDisplay | Number | 3 | Max number of chips to show before grouping them into a +N badge. |
| closeOnSelect | Boolean | true | (Single select) Closes the dropdown after selecting an item. |
| allowAddNew | Boolean | false | Allows adding a new item based on the search query. |
| addNewMode | String | 'button' | How to trigger "add new": on 'button' click or 'enter' press. |
| addNewLabel | String | 'Add new record' | Text used in the "add new" button/prompt. |
Events
| Event | Payload | Description |
| :--- | :--- | :--- |
| update:modelValue | (value) | Fired on selection change. Used by v-model. |
| change | (value) | Fired on selection change, along with update:modelValue. |
| select | (item) | Fired when an item is selected. |
| deselect | (item) | Fired when an item is deselected. |
| clear | () | Fired when the global "clear" button is clicked. |
| focus | (event) | Fired when the component gains focus. |
| blur | (value) | Fired when the component loses focus. |
| add-new | (searchTerm) | Fired when the user triggers the "add new" action. |
Slots
$3
Controls the rendering of each item in the dropdown list.
| Slot Prop | Type | Description |
| :--- | :--- | :--- |
| item | Object | The full item object for the current row. |
| level | Number | The indentation level (0 for root items, 1 for children, etc.). |
$3
Controls the rendering of the entire trigger button area (overrides default text, chips, and placeholder).
| Slot Prop | Type | Description |
| :--- | :--- | :--- |
| selectedItems | Array | Array of the full selected item objects. |
| displayText | String | The default text that would have been displayed. |
| placeholder | String | The placeholder prop. |
| isLoading | Boolean | The isLoading prop. |
| removeItem | Function | A function to remove a selected item (pass the item object). |
| getItemLabel | Function | A helper function to get an item's label. |
| getItemValue | Function | A helper function to get an item's value. |
| visibleChips | Array | Array of item objects to be shown as visible chips. |
| hiddenChipsCount | Number | Number of chips that are hidden. |
| toggleMorePopover | Function | A function to toggle the "more items" popover. |
| moreTriggerRef | Ref` | A ref to attach to your custom "more" button for positioning. |