vue-multiselect-dropdown/README.md

A reusable Vue dropdown component with multi-select and search support

# vue-multiselect-custom-dropdown

A flexible and elegant Vue 3 component for multiselect and single-select dropdowns with search, keyboard navigation, custom placeholders, and validation support. Perfect for forms and complex selection UIs.

![npm](https://img.shields.io/npm/v/vue-multiselect-custom-dropdown.svg)
![license](https://img.shields.io/npm/l/vue-multiselect-custom-dropdown.svg)

## ✨ Features

- ✅ Single & Multiple select modes
- 🔍 Searchable dropdown
- 🎨 Fully customizable styles (scoped CSS)
- 📦 Small footprint – optimized for Vue 3 + Vite
- ⌨️ Keyboard navigation support (arrow keys, Enter, Esc)
- ❌ Tag removal in multi-select mode
- 🧪 Built-in validation message support
- 🧩 Works well in forms

---

## 📦 Installation

```bash
npm i vue-multiselect-dropdown
```


### Register the component
Global registration
```bash
// main.js or main.ts
import { createApp } from 'vue';
import App from './App.vue';
import MultiselectCustomDropDown from 'vue-multiselect-dropdown';

const app = createApp(App);
app.component('MultiselectCustomDropDown', MultiselectCustomDropDown);
app.mount('#app');
```
### Local registration
```bash
import MultiselectCustomDropDown from 'vue-multiselect-dropdown';

export default {
  components: {
    MultiselectCustomDropDown
  }
};

```
```bash
<template>
  <MultiselectCustomDropDown
    v-model="selected"
    :options="dropdownOptions"
    :multiple="true"
    :searchable="true"
    label="Select Users"
    placeholder="Choose..."
    :required="true"
    labelKey="name"
    valueKey="id"
    error="This field is required"
  />
</template>

<script setup>
import { ref } from 'vue';

const selected = ref([]);

const dropdownOptions = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' }
];
</script>
```


| Prop          | Type                  | Default              | Description                            |
| ------------- | --------------------- | -------------------- | -------------------------------------- |
| `modelValue`  | `Array/Object/String` | `[]`                 | Selected value(s), supports v-model    |
| `options`     | `Array`               | `[]`                 | Array of dropdown options              |
| `multiple`    | `Boolean`             | `false`              | Enable multi-select mode               |
| `searchable`  | `Boolean`             | `false`              | Enable search input                    |
| `placeholder` | `String`              | `"Select an option"` | Placeholder text                       |
| `label`       | `String`              | `""`                 | Optional label for the dropdown        |
| `required`    | `Boolean`             | `false`              | Show red asterisk if required          |
| `error`       | `String`              | `""`                 | Error message below the field          |
| `labelKey`    | `String`              | `"name"`             | Key in option object for label display |
| `valueKey`    | `String`              | `"value"`            | Key in option object for unique value  |