\r\n\r\n### ๐ฏ **Core Features**\r\n\r\n- **Single & Multiple Selection** - Standard and multi-select modes\r\n- **Real-time Search** - Filter options as you type\r\n- **Tag Creation** - Users can create new options dynamically\r\n- **Clear Button** - Easy reset functionality\r\n- **Keyboard Navigation** - Full accessibility support\r\n- **Form Integration** - Works seamlessly with HTML forms\r\n\r\n
\r\n
\r\n\r\n### ๐ **Advanced Features**\r\n\r\n- **Remote API Loading** - Load data from REST endpoints\r\n- **Custom Templates** - Rich HTML templates for options\r\n- **Dark/Light Themes** - Bootstrap 5 theme integration\r\n- **Event System** - Comprehensive event callbacks\r\n- **Responsive Design** - Mobile-first responsive layout\r\n- **Performance Optimized** - Efficient rendering for large datasets\r\n\r\n
\r\n
\r\n
\r\n\r\n---\r\n\r\n## ๐ฏ Quick Start\r\n\r\n### Installation\r\n\r\n#### Option 1: Direct Download\r\n\r\n```html\r\n\r\n\r\n\r\n\r\n```\r\n\r\n#### Option 2: CDN\r\n\r\n```html\r\n\r\n\r\n\r\n\r\n```\r\n\r\n#### Option 3: NPM\r\n\r\n```bash\r\nnpm install @alizharb/bootstrap-multiselect\r\n```\r\n\r\n### Requirements\r\n\r\n- **Bootstrap 5.0+** (Required for styling)\r\n- **Modern Browser** with ES6+ support\r\n\r\n### Basic Usage\r\n\r\n```html\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```\r\n\r\n---\r\n\r\n## ๐ก Examples\r\n\r\n### Basic Select\r\n\r\n```html\r\n\r\n```\r\n\r\n### Searchable Multi-Select\r\n\r\n```html\r\n\r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n### Tags (Creatable Options)\r\n\r\n```html\r\n\r\n \r\n \r\n \r\n\r\n```\r\n\r\n### Remote API Integration\r\n\r\n```html\r\n\r\n```\r\n\r\n### Custom Templates\r\n\r\n```javascript\r\nazhSelect.init(\"#customSelect\", {\r\n templateOption: (opt) => {\r\n return `${opt.label}`;\r\n },\r\n templateValue: (opt) => {\r\n return `${opt.label}`;\r\n },\r\n});\r\n```\r\n\r\n---\r\n\r\n## โ๏ธ Configuration\r\n\r\n### Data Attributes\r\n\r\n| Attribute | Type | Default | Description |\r\n| ------------------ | ------- | ------------- | --------------------------------- |\r\n| `data-search` | Boolean | `false` | Enable search functionality |\r\n| `data-clear` | Boolean | `false` | Show clear button |\r\n| `data-tags` | Boolean | `false` | Allow tag creation |\r\n| `data-remote` | Boolean | `false` | Enable remote data loading |\r\n| `data-endpoint` | String | `null` | API endpoint URL |\r\n| `data-placeholder` | String | `\"Select...\"` | Placeholder text |\r\n| `data-max` | Number | `null` | Maximum selections (multi-select) |\r\n| `data-value-field` | String | `\"id\"` | API response value field |\r\n| `data-label-field` | String | `\"name\"` | API response label field |\r\n| `data-min-query` | Number | `1` | Minimum chars for remote search |\r\n| `data-delay` | Number | `300` | Remote search delay (ms) |\r\n| `data-preload` | Boolean | `false` | Preload remote data |\r\n| `data-bs-theme` | String | `\"light\"` | Bootstrap theme |\r\n\r\n### JavaScript Options\r\n\r\n```javascript\r\nazhSelect.init(\".azh-select\", {\r\n // Template functions\r\n templateOption: (opt) => opt.label,\r\n templateValue: (opt) => opt.label,\r\n\r\n // Internationalization\r\n i18n: {\r\n placeholder: \"Select...\",\r\n clear: \"Clear\",\r\n noResults: \"No results found\",\r\n },\r\n});\r\n```\r\n\r\n---\r\n\r\n## ๐จ Theming\r\n\r\nazh-select fully supports Bootstrap 5's theme system with automatic dark/light mode detection.\r\n\r\n### Theme Integration\r\n\r\n```html\r\n\r\n\r\n \r\n \r\n\r\n```\r\n\r\n### Custom Styling\r\n\r\n```css\r\n.my-custom-select {\r\n --azh-bg: #f0f8ff;\r\n --azh-border: #4682b4;\r\n --azh-text: #1e3a8a;\r\n --azh-hover-bg: rgba(70, 130, 180, 0.1);\r\n --azh-selected-bg: rgba(70, 130, 180, 0.2);\r\n}\r\n```\r\n\r\n### Dynamic Theme Switching\r\n\r\n```javascript\r\nfunction toggleTheme() {\r\n const html = document.documentElement;\r\n const currentTheme = html.getAttribute(\"data-bs-theme\");\r\n const newTheme = currentTheme === \"dark\" ? \"light\" : \"dark\";\r\n html.setAttribute(\"data-bs-theme\", newTheme);\r\n}\r\n```\r\n\r\n---\r\n\r\n## ๐ง API Reference\r\n\r\n### Global Methods\r\n\r\n| Method | Parameters | Description |\r\n| ------------------------ | ------------------- | -------------------------- |\r\n| `azhSelect.init()` | `selector, options` | Initialize select elements |\r\n| `azhSelect.get()` | `selector` | Get instance by selector |\r\n| `azhSelect.destroy()` | `selector` | Destroy specific instance |\r\n| `azhSelect.destroyAll()` | - | Destroy all instances |\r\n\r\n### Instance Methods\r\n\r\n| Method | Description |\r\n| ----------- | --------------------- |\r\n| `clear()` | Clear all selections |\r\n| `open()` | Open dropdown |\r\n| `close()` | Close dropdown |\r\n| `toggle()` | Toggle dropdown state |\r\n| `destroy()` | Destroy instance |\r\n\r\n### Events\r\n\r\n| Event | Trigger | Detail |\r\n| ------------------- | -------------------- | ---------------------------- |\r\n| `azh:change` | Selection changes | `{instance}` |\r\n| `azh:clear` | Clear button clicked | `{instance}` |\r\n| `azh:open` | Dropdown opens | `{instance}` |\r\n| `azh:close` | Dropdown closes | `{instance}` |\r\n| `azh:optionCreated` | New tag created | `{instance, value}` |\r\n| `azh:remoteLoaded` | Remote data loaded | `{instance, query, options}` |\r\n| `azh:error` | Remote API error | `{instance, error}` |\r\n\r\n### Event Usage\r\n\r\n```javascript\r\ndocument\r\n .querySelector(\"#mySelect\")\r\n .addEventListener(\"azh:change\", function (e) {\r\n console.log(\"Selection changed:\", e.target.value);\r\n });\r\n\r\ndocument\r\n .querySelector(\"#mySelect\")\r\n .addEventListener(\"azh:optionCreated\", function (e) {\r\n console.log(\"New tag created:\", e.detail.value);\r\n });\r\n```\r\n\r\n---\r\n\r\n## ๐ Remote API Integration\r\n\r\n### Server Requirements\r\n\r\nYour API should return JSON arrays:\r\n\r\n```json\r\n[\r\n { \"id\": 1, \"name\": \"John Doe\", \"email\": \"john@example.com\" },\r\n { \"id\": 2, \"name\": \"Jane Smith\", \"email\": \"jane@example.com\" }\r\n]\r\n```\r\n\r\n### Search Implementation\r\n\r\nWhen search is enabled, queries are sent as URL parameters:\r\n\r\n```\r\nGET /api/users?q=john\r\n```\r\n\r\n### Server Examples\r\n\r\n\r\nPHP (Laravel)\r\n\r\n```php\r\nRoute::get('/api/users', function (Request $request) {\r\n $query = $request->get('q');\r\n\r\n return User::when($query, function ($q) use ($query) {\r\n return $q->where('name', 'LIKE', \"%{$query}%\")\r\n ->orWhere('email', 'LIKE', \"%{$query}%\");\r\n })\r\n ->select('id', 'name', 'email')\r\n ->limit(50)\r\n ->get();\r\n});\r\n```\r\n\r\n\r\n\r\n\r\nNode.js (Express)\r\n\r\n```javascript\r\napp.get(\"/api/users\", (req, res) => {\r\n const query = req.query.q;\r\n let sql = \"SELECT id, name, email FROM users\";\r\n let params = [];\r\n\r\n if (query) {\r\n sql += \" WHERE name LIKE ? OR email LIKE ?\";\r\n params = [`%${query}%`, `%${query}%`];\r\n }\r\n\r\n db.query(sql + \" LIMIT 50\", params, (err, results) => {\r\n if (err) return res.status(500).json({ error: err.message });\r\n res.json(results);\r\n });\r\n});\r\n```\r\n\r\n\r\n\r\n\r\nPython (Django)\r\n\r\n```python\r\nfrom django.http import JsonResponse\r\nfrom django.db.models import Q\r\n\r\ndef users_api(request):\r\n query = request.GET.get('q', '')\r\n users = User.objects.all()\r\n\r\n if query:\r\n users = users.filter(\r\n Q(name__icontains=query) | Q(email__icontains=query)\r\n )\r\n\r\n return JsonResponse(\r\n list(users.values('id', 'name', 'email')[:50]),\r\n safe=False\r\n )\r\n```\r\n\r\n\r\n\r\n---\r\n\r\n## ๐ง Advanced Usage\r\n\r\n### Form Integration\r\n\r\n```html\r\n\r\n```\r\n\r\n### Framework Integration\r\n\r\n\r\nReact\r\n\r\n```jsx\r\nimport React, { useEffect, useRef } from \"react\";\r\nimport azhSelect from \"azh-select\";\r\n\r\nfunction AzhSelectComponent({ options, value, onChange }) {\r\n const selectRef = useRef();\r\n\r\n useEffect(() => {\r\n azhSelect.init(selectRef.current);\r\n selectRef.current.addEventListener(\"azh:change\", onChange);\r\n\r\n return () => azhSelect.destroy(selectRef.current);\r\n }, []);\r\n\r\n return (\r\n \r\n );\r\n}\r\n```\r\n\r\n\r\n\r\n\r\nVue.js\r\n\r\n```vue\r\n\r\n \r\n\r\n\r\n\r\n```\r\n\r\n\r\n\r\n---\r\n\r\n## ๐ ๏ธ Development\r\n\r\n### Building from Source\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/alizharb/azh-select.git\r\ncd azh-select\r\n\r\n# Install dependencies\r\nnpm install\r\n\r\n# Build for production\r\nnpm run build\r\n\r\n# Development with live reload\r\nnpm run dev\r\n\r\n# Run tests\r\nnpm test\r\n```\r\n\r\n### Project Structure\r\n\r\n```\r\nazh-select/\r\nโโโ dist/\r\nโ โโโ js/\r\nโ โ โโโ azh-select.js\r\nโ โ โโโ azh-select.min.js\r\nโ โโโ css/\r\nโ โ โโโ azh-select.css\r\nโ โ โโโ azh-select.min.css\r\nโ โโโ scss/\r\nโ โ โโโ azh-select.scss\r\nโ โโโ less/\r\nโ โโโ azh-select.less\r\nโโโ types/ # TypeScript typings\r\n```\r\n\r\n---\r\n\r\n## ๐งช Browser Support\r\n\r\n| Browser | Version | Notes |\r\n| ------- | ------- | --------------- |\r\n| Chrome | 60+ | โ Full support |\r\n| Firefox | 55+ | โ Full support |\r\n| Safari | 12+ | โ Full support |\r\n| Edge | 79+ | โ Full support |\r\n| IE | โ | Not supported |\r\n\r\n### Feature Support\r\n\r\n- **CSS Custom Properties**: All supported browsers\r\n- **Fetch API**: All supported browsers\r\n- **Custom Events**: All supported browsers\r\n- **ES6 Classes**: All supported browsers\r\n\r\n---\r\n\r\n## ๐ค Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n### Ways to Contribute\r\n\r\n- ๐ **Bug Reports** - Found an issue? Let us know!\r\n- ๐ก **Feature Requests** - Have an idea? Share it!\r\n- ๐ **Documentation** - Help improve our docs\r\n- ๐ง **Code** - Submit pull requests\r\n- ๐งช **Testing** - Help test new features\r\n\r\n### Development Setup\r\n\r\n1. Fork the repository\r\n2. Create a feature branch: `git checkout -b feature-name`\r\n3. Make your changes and test thoroughly\r\n4. Submit a pull request with a clear description\r\n\r\n---\r\n\r\n## ๐ License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\r\n## ๐ Acknowledgments\r\n\r\n- **Bootstrap Team** - For the amazing CSS framework\r\n- **Contributors** - Everyone who has contributed to this project\r\n- **Community** - For feedback, bug reports, and feature suggestions\r\n\r\n---\r\n\r\n## ๐ Support\r\n\r\n- ๐ **Documentation**: [Full Documentation](https://alizharb.github.io/azh-select)\r\n- ๐ **Bug Reports**: [GitHub Issues](https://github.com/alizharb/azh-select/issues)\r\n- ๐ฌ **Discussions**: [GitHub Discussions](https://github.com/alizharb/azh-select/discussions)\r\n- ๐ง **Email**: harbzali@gmail.com\r\n\r\n---\r\n\r\n