{"id":23060019,"url":"https://github.com/amdad121/select2-vue","last_synced_at":"2026-01-12T13:59:00.011Z","repository":{"id":267319796,"uuid":"900450255","full_name":"amdad121/select2-vue","owner":"amdad121","description":"Select2 Component for VueJS","archived":false,"fork":false,"pushed_at":"2024-12-18T18:49:39.000Z","size":21,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T20:47:37.354Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amdad121.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-08T19:56:32.000Z","updated_at":"2024-12-18T18:49:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"9b5d04ff-a141-4ab4-a3d3-18697582140a","html_url":"https://github.com/amdad121/select2-vue","commit_stats":null,"previous_names":["amdad121/select2-vue"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fselect2-vue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fselect2-vue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fselect2-vue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fselect2-vue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amdad121","download_url":"https://codeload.github.com/amdad121/select2-vue/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246952279,"owners_count":20859812,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-16T03:11:17.298Z","updated_at":"2026-01-12T13:58:59.993Z","avatar_url":"https://github.com/amdad121.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Select2 Component for Vue\n\n[![npm version](https://badge.fury.io/js/select2-vue.svg)](https://badge.fury.io/js/select2-vue)\n[![Downloads](https://img.shields.io/npm/dm/select2-vue.svg)](https://www.npmjs.com/package/select2-vue)\n[![Total Downloads](https://img.shields.io/npm/dt/select2-vue.svg)](https://www.npmjs.com/package/select2-vue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Vue 3](https://img.shields.io/badge/Vue-3-42b883?style=flat\u0026logo=vue.js)](https://vuejs.org/)\n[![Bundle Size](https://img.shields.io/bundlephobia/minzip/select2-vue)](https://bundlephobia.com/result?p=select2-vue)\n\n**`select2-vue`** is a Vue.js wrapper component for the popular jQuery Select2 library, providing you with a flexible and customizable select box with support for searching, tagging, remote data sources, and more. The package makes it easy to integrate the powerful features of Select2 into your Vue applications.\n\n## Features\n\n-   Support for all Select2 features (search, tagging, remote data, infinite scrolling).\n-   Fully reactive with Vue.js.\n-   Easy integration with existing Select2 options.\n-   Configurable using props for quick customization.\n-   Emits native Select2 events for more control.\n\n## Installation\n\nInstall the package via npm:\n\n```bash\nnpm install select2-vue\n```\n\nOr via yarn:\n\n```bash\nyarn add select2-vue\n```\n\nOr via pnpm:\n\n```bash\npnpm add select2-vue\n```\n\n## Basic Usage\n\nImport and register the `select2-vue` component, using the `\u003cscript setup\u003e` syntax for simplicity.\n\n### Example: Basic Select\n\n```vue\n\u003ctemplate\u003e\n    \u003cselect2-vue :options=\"selectOptions\" v-model=\"selectedValue\" :config=\"{ placeholder: 'Select an option' }\" /\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\nimport Select2 from 'select2-vue';\n\nconst selectedValue = ref(null);\nconst selectOptions = [\n    { id: 1, text: 'Option 1' },\n    { id: 2, text: 'Option 2' },\n    { id: 3, text: 'Option 3' },\n];\n\u003c/script\u003e\n```\n\n## TypeScript Support\n\nThis package includes TypeScript type definitions out of the box. The component and its utility functions are fully typed.\n\n### TypeScript Example\n\n```vue\n\u003ctemplate\u003e\n    \u003cselect2-vue\n        :options=\"countries\"\n        v-model=\"selectedCountry\"\n        :config=\"{ placeholder: 'Select a country' }\"\n        @select=\"handleSelect\"\n    /\u003e\n\u003c/template\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { ref } from 'vue';\nimport Select2, { Select2Option, Select2Config } from 'select2-vue';\n\ninterface Country extends Select2Option {\n    code: string;\n}\n\nconst selectedCountry = ref\u003cstring | null\u003e(null);\n\nconst countries: Country[] = [\n    { id: 1, text: 'United States', code: 'US' },\n    { id: 2, text: 'Canada', code: 'CA' },\n    { id: 3, text: 'United Kingdom', code: 'UK' },\n];\n\nconst select2Config: Select2Config = {\n    placeholder: 'Select a country',\n    allowClear: true,\n};\n\nfunction handleSelect(option: Country) {\n    console.log('Selected:', option);\n}\n\u003c/script\u003e\n```\n\n### TypeScript Types\n\n```ts\nimport type { Select2Option, Select2Config, Select2AjaxOptions } from 'select2-vue';\n\n// Define your option type extending Select2Option\ninterface MyOption extends Select2Option {\n    customProperty: string;\n}\n\n// Configure Select2 with typed options\nconst config: Select2Config = {\n    minimumResultsForSearch: 10,\n    tags: true,\n};\n\n// Setup ajax with typed options\nconst ajaxOptions: Select2AjaxOptions = {\n    url: '/api/search',\n    dataType: 'json',\n    delay: 250,\n    processResults: (data: any) =\u003e ({\n        results: data.items,\n    }),\n};\n```\n\n### Styles\n\nTo ensure proper styling, include the **Select2** CSS file in your project:\n\n```js\nimport 'select2/dist/css/select2.css';\n```\n\n## Props\n\nThe `select2-vue` component accepts the following props for customization:\n\n| Prop          | Type      | Default     | Description                                                                                                                                                            |\n| ------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `options`     | `Array`   | `[]`        | Array of select options. Each option should be an object with `id` and `text` properties.                                                                              |\n| `modelValue`  | `Any`     | `null`      | The currently selected value (can be bound with `v-model`).                                                                                                            |\n| `multiple`    | `Boolean` | `false`     | Enables multiple selection.                                                                                                                                            |\n| `disabled`    | `Boolean` | `false`     | Disables the select box.                                                                                                                                               |\n| `config`      | `Object`  | `{}`        | Custom settings to pass directly to the underlying Select2 instance (including `placeholder`). See [Select2 documentation](https://select2.org/configuration/options-api) for available options. |\n| `ajaxOptions` | `Object`  | `null`      | Ajax options for remote data loading.                                                                                                                                 |\n| `valueKey`    | `String`  | `'id'`      | Key to use for the option value.                                                                                                                                      |\n| `textKey`     | `String`  | `'text'`    | Key to use for the option text.                                                                                                                                       |\n\n## Events\n\nThe component emits several useful events for better control over the Select2 instance:\n\n| Event              | Description                                                                         |\n| ------------------ | ----------------------------------------------------------------------------------- |\n| `select2:select`   | Fired when an option is selected. The selected item is passed as the event payload. |\n| `select2:unselect` | Fired when an option is deselected (in `multiple` mode).                            |\n| `select2:opening`  | Triggered when the dropdown is about to open.                                       |\n| `select2:closing`  | Triggered when the dropdown is about to close.                                      |\n| `change`           | Fired when the value changes, passing the new value.                                |\n\nExample:\n\n```vue\n\u003ctemplate\u003e\n    \u003cselect2-vue\n        :options=\"selectOptions\"\n        v-model=\"selectedValue\"\n        @select2:select=\"handleSelect\"\n        @select2:unselect=\"handleUnselect\"\n    /\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\n\nconst selectedValue = ref(null);\nconst selectOptions = [\n    { id: 1, text: 'Option 1' },\n    { id: 2, text: 'Option 2' },\n    { id: 3, text: 'Option 3' },\n];\n\nfunction handleSelect(selected) {\n    console.log('Option selected:', selected);\n}\n\nfunction handleUnselect(unselected) {\n    console.log('Option unselected:', unselected);\n}\n\u003c/script\u003e\n```\n\n### Comprehensive Event Reference\n\nAll standard Select2 events are available. Here's a complete list:\n\n| Event               | Description                                                | Parameters                          |\n| ------------------- | ---------------------------------------------------------- | ----------------------------------- |\n| `change`            | Fired when the value changes                               | `(value: string | string[])`       |\n| `select`            | Fired when an option is selected                           | `(option: Select2Option)`          |\n| `select2:open`      | Triggered when the dropdown opens                           | -                                   |\n| `select2:closing`   | Triggered when the dropdown is about to close              | -                                   |\n| `select2:closed`    | Triggered when the dropdown has closed                     | -                                   |\n| `select2:select`    | Fired when a selection is made                             | `(params: { data: Select2Option })` |\n| `select2:unselect`  | Fired when a selection is removed                          | `(params: { data: Select2Option })` |\n\n### Advanced Event Example\n\n```vue\n\u003ctemplate\u003e\n    \u003cselect2-vue\n        :options=\"options\"\n        v-model=\"value\"\n        @select2:opening=\"onOpening\"\n        @select2:closing=\"onClosing\"\n        @select2:select=\"onSelect\"\n        @select2:unselect=\"onUnselect\"\n        @change=\"onChange\"\n    /\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\n\nconst value = ref(null);\nconst options = [\n    { id: 1, text: 'Option 1' },\n    { id: 2, text: 'Option 2' },\n];\n\nconst onOpening = () =\u003e console.log('Dropdown opening');\nconst onClosing = () =\u003e console.log('Dropdown closing');\nconst onSelect = (e) =\u003e console.log('Selected:', e.params.data);\nconst onUnselect = (e) =\u003e console.log('Unselected:', e.params.data);\nconst onChange = (val) =\u003e console.log('Value changed:', val);\n\u003c/script\u003e\n```\n\n## Advanced Usage\n\n### Using Global Configuration\n\nSet global Select2 options that apply to all instances:\n\n```vue\n\u003ctemplate\u003e\n    \u003cdiv\u003e\n        \u003cselect2-vue :options=\"options1\" v-model=\"value1\" /\u003e\n        \u003cselect2-vue :options=\"options2\" v-model=\"value2\" /\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\nimport Select2, { setGlobalSelect2Options } from 'select2-vue';\n\n// Set global options for all Select2 instances\nsetGlobalSelect2Options({\n    width: '100%',\n    dropdownParent: 'body',\n});\n\nconst value1 = ref(null);\nconst value2 = ref(null);\nconst options1 = [{ id: 1, text: 'A' }];\nconst options2 = [{ id: 1, text: 'B' }];\n\u003c/script\u003e\n```\n\n### Custom Option Keys\n\nUse custom keys for your options:\n\n```vue\n\u003ctemplate\u003e\n    \u003cselect2-vue\n        :options=\"users\"\n        v-model=\"selectedUserId\"\n        value-key=\"userId\"\n        text-key=\"userName\"\n        :config=\"{ placeholder: 'Select a user' }\"\n    /\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\n\nconst selectedUserId = ref(null);\nconst users = [\n    { userId: 101, userName: 'Alice Johnson' },\n    { userId: 102, userName: 'Bob Smith' },\n    { userId: 103, userName: 'Carol White' },\n];\n\u003c/script\u003e\n```\n\n### Using Remote Data\n\nYou can fetch data dynamically from a remote API using the `config` prop:\n\n```vue\n\u003ctemplate\u003e\n    \u003cselect2-vue :config=\"select2Settings\" v-model=\"selectedValue\" :options=\"[]\" /\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\n\nconst selectedValue = ref(null);\nconst select2Settings = {\n    ajax: {\n        url: 'https://api.example.com/data',\n        dataType: 'json',\n        processResults: function (data) {\n            return {\n                results: data.items.map((item) =\u003e ({\n                    id: item.id,\n                    text: item.name,\n                })),\n            };\n        },\n    },\n};\n\u003c/script\u003e\n```\n\n## Example: Multiple Selection with Tagging\n\nHere's an example where you can add new tags or select multiple values:\n\n```vue\n\u003ctemplate\u003e\n    \u003cselect2-vue :config=\"select2Settings\" v-model=\"selectedTags\" :options=\"[]\" :multiple=\"true\" placeholder=\"Select or add tags\" /\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\n\nconst selectedTags = ref([]);\nconst select2Settings = {\n    tags: true,\n    tokenSeparators: [',', ' '],\n};\n\u003c/script\u003e\n```\n\n## Troubleshooting \u0026 FAQ\n\n### Common Issues\n\n**Q: Why isn't the select box styled?**\n\nA: Make sure you import the Select2 CSS:\n\n```js\nimport 'select2/dist/css/select2.css';\n```\n\n**Q: How do I programmatically set the value?**\n\nA: Use `v-model` or update the ref bound to the component:\n\n```vue\n\u003cscript setup\u003e\nconst value = ref('initial-value');\n\nfunction resetSelection() {\n    value.value = null;\n}\n\nfunction setToFirstOption() {\n    value.value = 'option-1-id';\n}\n\u003c/script\u003e\n```\n\n**Q: The dropdown appears behind other elements**\n\nA: Use the `dropdownParent` config option:\n\n```vue\n\u003cscript setup\u003e\nconst config = {\n    dropdownParent: 'body', // or a specific element selector\n};\n\u003c/script\u003e\n```\n\n**Q: How do I clear the selection?**\n\nA: Set the value to `null`:\n\n```vue\n\u003cscript setup\u003e\nconst value = ref('some-value');\n\nfunction clear() {\n    value.value = null;\n}\n\u003c/script\u003e\n```\n\n**Q: Why are my options not showing when using `v-model`?**\n\nA: Ensure your options have matching `id` values to what you're setting in `v-model`. Also, the `options` array must be provided.\n\n**Q: Can I use this with Nuxt 3?**\n\nA: Yes! You need to configure it to work with SSR:\n\n```js\n// nuxt.config.js\nexport default {\n    build: {\n        transpile: ['select2-vue']\n    }\n}\n```\n\nThen wrap the component in a `\u003cClientOnly\u003e` tag:\n\n```vue\n\u003ctemplate\u003e\n    \u003cClientOnly\u003e\n        \u003cselect2-vue :options=\"options\" v-model=\"value\" /\u003e\n    \u003c/ClientOnly\u003e\n\u003c/template\u003e\n```\n\n### Performance Tips\n\n1. **For large datasets (1000+ options)**: Consider using remote/ajax loading instead of passing all options as props.\n2. **Debounce search input**: Use Select2's built-in `delay` option for ajax searches.\n3. **Avoid unnecessary re-renders**: Ensure your options array reference is stable when options haven't changed.\n\n## Browser Support\n\nThis component supports all modern browsers that support:\n- Vue 3\n- ES6+ JavaScript\n- jQuery 3.7+\n\nTested and working on:\n- Chrome/Edge (latest)\n- Firefox (latest)\n- Safari (latest)\n- Mobile browsers (iOS Safari, Chrome Mobile)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famdad121%2Fselect2-vue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famdad121%2Fselect2-vue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famdad121%2Fselect2-vue/lists"}