Vue 3 Vue Select Component


A powerful, flexible, and accessible select component for Vue 3.

This component provides a fully featured, searchable, and sortable dropdown tree. It's designed to be highly customizable, supporting single and multiple selection, checkbox modes, chip display, custom item rendering, and more.

Features

* Tree Structure: Infinitely nested tree support
* Single & Multiple Select: Use it for one item or many.
* Display Modes: Show selections as plain 'text' or as 'chips'.
* Selection Modes: Use familiar 'checkbox' UI or a simple 'highlight' on click.
* Powerful Search:
* Built-in filtering of all nodes.
* Supports searching multiple/nested keys (e.g., ['name', 'user.email']) via keyFilters.
* Sorting:
* Sort the items in the dropdown list by any key.
* Automatically sorts the selected "chips" (when multiple: true).
* "Add New" Item: Allows users to add items that aren't in the list (allowAddNew prop).
* Fully Customizable:
* Use the #default slot to render each tree item.
Use the #display slot to completely* customize the trigger/button area.
* Accessible: Built with accessibility in mind (keyboard navigation, ARIA attributes).
* Loading & Disabled States: Easily managed with isLoading and disabled props.
* ...and much more, like selectAll, disableBranchNodes, and size variants (sm, md, lg, xl).

Installation

Install with npm

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

---