Overview
The <web-multiselect> web component provides a rich, accessible multiselect interface with extensive customization options.
Public Properties
| Property | Type | Description |
|---|---|---|
options | T[] | Array of items to display in the dropdown |
selectedValue | string | number | (string | number)[] | null | Get selected value(s). Returns single value in single-select mode, array in multi-select mode |
selectedItem | T | null | Get the first selected item object |
Properties Example
Public Methods
getValue()
Returns the current selected value(s) in a form-ready format.
- Returns:
string | number | (string | number)[] | null - Behavior: Mode-dependent. Returns single value in single-select mode, array in multi-select mode
getSelected()
Returns array of selected item objects.
- Returns:
T[] - Behavior: Always returns an array of full item objects
setSelected(values)
Set selected values programmatically.
- Parameters:
values: (string | number)[] - Returns:
void
destroy()
Clean up the component and remove all event listeners.
- Returns:
void
Callback Properties
Set these properties to customize data extraction and behavior:
| Property | Type | Description |
|---|---|---|
getValueCallback | (item: T) => string | number | Extract unique ID from item |
getDisplayValueCallback | (item: T) => string | Extract display text from item |
getSearchValueCallback | (item: T) => string | Extract searchable text from item |
getIconCallback | (item: T) => string | Extract icon/emoji from item |
getSubtitleCallback | (item: T) => string | Extract subtitle/description from item |
getGroupCallback | (item: T) => string | Extract group name from item |
getDisabledCallback | (item: T) => boolean | Determine if item is disabled |
getFormValueCallback | (values: (string | number)[]) => string | Custom form value formatting |
searchCallback | (searchTerm: string) => Promise<T[]> | Async function to load data |
addNewCallback | (value: string) => T | Promise<T> | Create new option when adding |
selectCallback | (option: T) => void | Called when option is selected |
deselectCallback | (option: T) => void | Called when option is deselected |
changeCallback | (selectedOptions: T[]) => void | Called when selection changes |
Callbacks Example
Custom Events
The component dispatches these custom events:
| Event | Detail Type | Description |
|---|---|---|
select | MultiSelectEventDetail<T> | Dispatched when an option is selected |
deselect | MultiSelectEventDetail<T> | Dispatched when an option is deselected |
change | MultiSelectEventDetail<T> | Dispatched when selection changes |
Events Example
TypeScript Support
The component is fully typed with generic support:
TypeScript Example
Global API
Access component functionality through the global API namespace window.keenmate.multiselect:
| Method / Property | Returns | Description |
|---|---|---|
version() | string | Returns the component version |
config | object | Package metadata (name, version, author, license, repository, homepage) |
register() | void | Manually register the custom element (if not auto-registered) |
getInstances() | HTMLElement[] | Get all active multiselect instances on the page |
Usage Examples
Check Component Version
Version Info
Get All Instances
Instance Management
Manual Registration
Manual Registration
💡 Use Cases:
- Version Detection: Check component version in bundled projects
- Global State: Access all instances for batch operations
- Debugging: Inspect instances in browser console
- Testing: Programmatically interact with all instances
📝 Important Notes
- Generic Types: Component supports any data structure via
Tparameter - Reactive: All properties are reactive - changes update the UI automatically
- Shadow DOM: Component uses Shadow DOM for encapsulation
- Form Integration: Works seamlessly with HTML forms via hidden inputs
- Cleanup: Always call
destroy()when removing from DOM