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

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

1. #default Slot

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

2. #display Slot

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