# 🎯 ark-select-single

[![npm version](https://img.shields.io/npm/v/ark-select-single.svg?style=flat-square)](https://www.npmjs.com/package/ark-select-single)
[![npm downloads](https://img.shields.io/npm/dm/ark-select-single.svg?style=flat-square)](https://www.npmjs.com/package/ark-select-single)
[![jsDelivr hits](https://img.shields.io/jsdelivr/npm/hm/ark-select-single?style=flat-square)](https://www.jsdelivr.com/package/npm/ark-select-single)
[![license](https://img.shields.io/npm/l/ark-select-single?style=flat-square)](LICENSE)

**ark-select-single** is a zero‑dependency JavaScript library that turns any ordinary `<select>` element into a fully searchable dropdown. All styles are embedded – no external CSS files required. It also provides simple methods to dynamically add or remove options.

---

## Demo Link

You may be using [Demo Link](https://ark-select-single.immanuel.co/demo.html).

---

## ✨ Features

- 🔍 **Live search/filter** – type to narrow down options.
- ⌨️ **Keyboard navigation** – arrow keys, Enter to select, Esc to close.
- 🎨 **Self‑styled** – all CSS injected automatically.
- 📦 **Tiny footprint** – no dependencies, just vanilla JS.
- 🔧 **Dynamic options** – add/remove options after initialization.
- 🧩 **Framework‑agnostic** – works with any project (React, Vue, plain HTML).

---

## 🚀 Installation

### npm / yarn
```bash
npm install ark-select-single
# or
yarn add ark-select-single

---

### CDN (unpkg) – also allows direct file download
```html
<script src="https://cdn.jsdelivr.net/npm/ark-select-single@latest/ark-select-single.js"></script>
```

> **Note:** The library is **not** available on cdnjs. Please use the jsDelivr or unpkg links above.  
> If you need a local copy, right‑click [this link](https://cdn.jsdelivr.net/npm/ark-select-single@latest/ark-select-single.js) and select **"Save link as…"** to download the minified file.

The library is exposed globally as `ArkSearchableSelect`.

---

## 📖 Basic Usage

1. Include the library (either via npm import or CDN script).
2. Add a standard `<select>` element with some `<option>` children.
3. Create a new instance by passing a CSS selector or DOM element.

### Example
```html
<select id="fruit-select">
  <option value="apple">Apple</option>
  <option value="banana">Banana</option>
  <option value="cherry">Cherry</option>
  <option value="date">Date</option>
</select>

<script src="https://cdn.jsdelivr.net/npm/ark-select-single@latest/ark-select-single.js"></script>
<script>
  new ArkSearchableSelect('#fruit-select');
</script>
```

That’s it! The original select is automatically hidden and its value stays in sync.

![Demo screenshot](demo_1.gif) <!-- replace with actual screenshot if available -->

---

## 🧠 API Reference

### Constructor
```js
new ArkSearchableSelect(selector)
```
- **selector** – a CSS selector string **or** a DOM element pointing to an existing `<select>`.

### Methods

| Method | Description |
|--------|-------------|
| `addOption(value, text, position)` | Adds a new option. See [Dynamic Options](#-dynamic-options) for details. |
| `removeOption(value)` | Removes all options with the given `value`. |

Both methods automatically refresh the dropdown UI and keep the selected value consistent.

---

## 🔧 Dynamic Options

You can add or remove options at any time after initialization.

### `addOption(value, text, position)`
- **value** (string) – the option’s `value` attribute.
- **text** (string) – the displayed text.
- **position** (optional) – where to insert the new option. Can be:
  - A **number** (0‑based index) – inserts at that exact position.
  - `'last'` – appends at the end (default).
  - `'alpha'` – inserts in **case‑insensitive alphabetical order** based on the displayed text.

### `removeOption(value)`
- **value** (string) – removes every option whose `value` matches this string.  
  If the currently selected option is removed, the first remaining option (if any) becomes selected.

### Example
```js
const mySelect = new ArkSearchableSelect('#my-select');

// Add options
mySelect.addOption('plum', 'Plum', 'last');      // append at the end
mySelect.addOption('apricot', 'Apricot', 'alpha'); // insert alphabetically
mySelect.addOption('kiwi', 'Kiwi', 2);             // insert at index 2

// Remove an option
mySelect.removeOption('banana');
```

Dynamic feature in the working recorded as gif

![Demo screenshot](demo_2.gif) <!-- replace with actual screenshot if available -->

---

## 🎨 Styling

All necessary styles are injected by the library. If you want to override them, use the following CSS classes:

| Class | Element |
|-------|---------|
| `.searchable-select-container` | Outer wrapper |
| `.searchable-select-display` | The box showing the selected value |
| `.searchable-select-dropdown` | Dropdown panel |
| `.searchable-select-search` | Search input inside the dropdown |
| `.searchable-select-options` | `<ul>` containing options |
| `.searchable-select-option` | Each option item |
| `.searchable-select-option.selected` | Currently selected option |
| `.searchable-select-option.highlighted` | Option highlighted via keyboard |

### Example override
```css
.searchable-select-container {
  max-width: 400px;
  font-family: 'Segoe UI', sans-serif;
}
.searchable-select-option.selected {
  background-color: #4f46e5;
  color: white;
}
```

---

## 🌐 Browser Support

Works in all modern browsers (Chrome, Firefox, Safari, Edge). Internet Explorer is **not** supported.

---

## 📄 License

[MIT](LICENSE) © [Immanuel R]
```

---

## 👤 Author

**Immanuel R**  
- Email: [raj@immanuel.co](mailto:raj@immanuel.co)  
- GitHub: [@ir-dev](https://github.com/ir-dev)
```