{"id":24491269,"url":"https://github.com/lcvriend/wc-multi-selector","last_synced_at":"2026-05-16T18:35:47.007Z","repository":{"id":165291135,"uuid":"568410258","full_name":"lcvriend/wc-multi-selector","owner":"lcvriend","description":"Web component that lets a user select multiple options from an arbitrarily nestable hierarchy within a drop-down menu","archived":false,"fork":false,"pushed_at":"2025-02-04T16:08:00.000Z","size":74,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-11T00:12:33.967Z","etag":null,"topics":["js","keyboard-navigation","multiselect","nestable","omnibox","searchable-dropdown","vanilla-js","web-component"],"latest_commit_sha":null,"homepage":"https://lcvriend.github.io/wc-multi-selector/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lcvriend.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-11-20T13:00:56.000Z","updated_at":"2025-02-04T16:08:04.000Z","dependencies_parsed_at":"2024-03-18T10:54:20.649Z","dependency_job_id":null,"html_url":"https://github.com/lcvriend/wc-multi-selector","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcvriend%2Fwc-multi-selector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcvriend%2Fwc-multi-selector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcvriend%2Fwc-multi-selector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcvriend%2Fwc-multi-selector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lcvriend","download_url":"https://codeload.github.com/lcvriend/wc-multi-selector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243673292,"owners_count":20328912,"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":["js","keyboard-navigation","multiselect","nestable","omnibox","searchable-dropdown","vanilla-js","web-component"],"created_at":"2025-01-21T18:17:36.509Z","updated_at":"2026-05-16T18:35:47.001Z","avatar_url":"https://github.com/lcvriend.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-Selector Web Component\n\nA lightweight, accessible web component for selecting multiple options from hierarchical data structures. Built with vanilla JavaScript and no external dependencies. Check out [this page](https://lcvriend.github.io/wc-multi-selector/) for several examples.\n\n\u003cimg src=\"./screenshots/ms-countries.png\" alt=\"Multi-selector with dropdown open\" width=\"496\"\u003e\n\n## Features\n\n- **Hierarchical Data**: Support for arbitrarily nested option groups\n- **Multiple Data Sources**: Load from JSON or define options in HTML markup\n- **Advanced Search**: Filter by labels or values with instant results\n- **Keyboard Navigation**: Full keyboard accessibility with intuitive shortcuts\n- **Form Integration**: Native form participation with proper validation\n- **Adaptive Theming**: Automatic dark/light mode detection with custom styling\n- **Accessibility**: WCAG compliant with proper ARIA attributes and focus management\n\n## Quick Start\n\n```html\n\u003c!-- Basic usage with JSON data --\u003e\n\u003cmulti-selector src=\"data/options.json\" name=\"my-options\"\u003e\u003c/multi-selector\u003e\n\n\u003c!-- Inline options --\u003e\n\u003cmulti-selector name=\"colors\"\u003e\n    \u003coption\u003eRed\u003c/option\u003e\n    \u003coption\u003eBlue\u003c/option\u003e\n    \u003coption\u003eGreen\u003c/option\u003e\n\u003c/multi-selector\u003e\n\n\u003c!-- Grouped options --\u003e\n\u003cmulti-selector name=\"instruments\"\u003e\n    \u003coptgroup label=\"String\"\u003e\n        \u003coption value=\"guitar\"\u003eGuitar\u003c/option\u003e\n        \u003coption value=\"violin\"\u003eViolin\u003c/option\u003e\n    \u003c/optgroup\u003e\n    \u003coptgroup label=\"Wind\"\u003e\n        \u003coption value=\"flute\"\u003eFlute\u003c/option\u003e\n        \u003coption value=\"trumpet\"\u003eTrumpet\u003c/option\u003e\n    \u003c/optgroup\u003e\n\u003c/multi-selector\u003e\n```\n\n## Installation\n\nSimply include the JavaScript file in your HTML:\n\n```html\n\u003cscript src=\"wc-multi-selector.js\"\u003e\u003c/script\u003e\n```\n\nThe component automatically registers itself as `\u003cmulti-selector\u003e`.\n\n## Data Structure\n\n### JSON Format\n\nEach option should follow this structure:\n\n```json\n{\n    \"label\": \"Display Text\",     // Optional - falls back to value\n    \"value\": \"unique_id\",        // Required\n    \"selected\": false,           // Optional - preselect option\n    \"children\": []               // Optional - for nested groups\n}\n```\n\n### Simplified Formats\n\nThe component automatically converts simpler formats:\n\n```json\n// Flat array\n[\"Option 1\", \"Option 2\", \"Option 3\"]\n\n// Nested object\n{\n    \"Group A\": [\"Item 1\", \"Item 2\"],\n    \"Group B\": [\"Item 3\", \"Item 4\"]\n}\n```\n\n## API Reference\n\n### Attributes\n\n| Attribute     | Type              | Description |\n|---------------|-------------------|-------------|\n| `src`         | string            | URL to JSON data source |\n| `name`        | string            | Form field name |\n| `placeholder` | string            | Text shown when no selections made |\n| `disabled`    | boolean           | Disable the component |\n| `mode`        | \"light\" \\| \"dark\" | Force theme mode (auto-detects if not set) |\n\n### Properties\n\n| Property         | Type   | Description |\n|------------------|--------|-------------|\n| `data`           | Array  | Get/set the options data |\n| `selectedValues` | Array  | Array of currently selected values |\n| `selectedLabels` | Array  | Array of currently selected labels |\n| `settings`       | Object | Component configuration options |\n\n### Methods\n\n| Method                   | Parameters | Description |\n|--------------------------|------------|-------------|\n| `addSelectedValues()`    | ...values  | Add values to selection |\n| `removeSelectedValues()` | ...values  | Remove values from selection |\n\n### Events\n\n| Event    | Detail                     | Description |\n|----------|----------------------------|-------------|\n| `change` | `{detail: selectedValues}` | Fired when selection changes |\n\n## Keyboard Shortcuts\n\n### Navigation\n- `↑` `↓` `←` `→` - Navigate options\n- `Home` / `End` - Jump to first/last option\n- `Tab` - Standard tab navigation\n- `Esc` - Close dropdown\n\n### Filtering \u0026 Folding\n- `Ctrl` + `\\` - Show only selected items\n- `Ctrl` + `/` - Clear search filter\n- `Ctrl` + `[` - Fold all groups\n- `Ctrl` + `]` - Unfold all groups\n\n## Styling\n\n### CSS Custom Properties\n\nThe component uses CSS custom properties for theming:\n\n```css\nmulti-selector {\n    /* Layout */\n    --ms-height: calc(2rem + var(--ms-padding-block));\n    --ms-max-height: 60vh;\n    --ms-padding-block: .25em;\n    --ms-padding-inline: 1em;\n    --ms-border-radius: 5px;\n\n    /* Colors */\n    --ms-text-color: inherit;\n    --ms-border-color: currentColor;\n    --ms-dropdown-background: hsl(0, 0%, 100%);\n    --ms-hover: hsl(0, 0%, 93%);\n}\n```\n\n### Shadow Parts\n\nUse `::part()` selectors for structural styling:\n\n```css\nmulti-selector::part(container) {\n    border-width: 2px;\n    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);\n}\n\nmulti-selector::part(dropdown) {\n    background: var(--custom-background);\n}\n```\n\nAvailable parts:\n- `container` - Main dropdown container\n- `display` - Selected items display\n- `controls` - Control button panel\n- `dropdown` - Dropdown content area\n- `filter` - Search section\n- `options` - Options container\n\n## Form Integration\n\nThe component participates in forms like native controls:\n\n```html\n\u003cform\u003e\n    \u003cmulti-selector name=\"preferences\" src=\"data.json\"\u003e\u003c/multi-selector\u003e\n    \u003cbutton type=\"submit\"\u003eSubmit\u003c/button\u003e\n\u003c/form\u003e\n```\n\nForm data is submitted as a JSON string of selected values.\n\n## Advanced Usage\n\n### Dynamic Data Management\n\n```javascript\nconst selector = document.querySelector('multi-selector')\n\n// Set data programmatically\nselector.data = [\n    { label: \"Option 1\", value: \"opt1\" },\n    { label: \"Option 2\", value: \"opt2\" }\n]\n\n// Listen for changes\nselector.addEventListener('change', event =\u003e {\n    console.log('Selected:', event.detail)\n})\n\n// Programmatically select options\nselector.addSelectedValues('opt1', 'opt2')\n```\n\n### Custom Settings\n\n```javascript\nselector.settings = {\n    labels: {\n        placeholder: \"Choose items...\",\n        filter: {\n            placeholder: \"Type to search...\"\n        }\n    },\n    titles: {\n        unfoldGroups: \"Expand all groups\",\n        showSelected: \"Show selected only\"\n    }\n}\n\n// Extend defaults\nMultiSelector.defaultSettings.labels.all = \"Alle items\"\n```\n\n## Alternatives\n\n- [BVSelect](https://bmsvieira.github.io/BVSelect-VanillaJS/)\n- [vanilla-select](https://vorotina.github.io/vanilla-select/)\n- [multiselect-combo-box](https://multiselect-combo-box.web.app/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcvriend%2Fwc-multi-selector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flcvriend%2Fwc-multi-selector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcvriend%2Fwc-multi-selector/lists"}