npm package: @night-owl-elite/vue-select
Description: [![npm](https://img.shields.io/npm/v/@night-owl-elite/vue-select.svg)](https://www.npmjs.com/package/@night-owl-elite/vue-select)
Latest version: 1.3.49

# Vue 3 Vue Select Component

[![npm](https://img.shields.io/npm/v/@night-owl-elite/vue-select.svg)](https://www.npmjs.com/package/@night-owl-elite/vue-select)

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
### 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. |

---