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 |
getBadgeDisplayCallback | (item: T) => string | Extract custom badge display text (defaults to display value) |
getBadgeClassCallback | (item: T) => string | string[] | Get CSS classes for individual badges |
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 |
renderGroupLabelContentCallback | (groupName: string) => string | HTMLElement | Custom rendering for group labels |
getDisabledCallback | (item: T) => boolean | Determine if item is disabled |
getValueFormatCallback | (values: (string | number)[]) => string | Custom form value formatting |
beforeSearchCallback | (searchTerm: string) => string | null | Transform search term before searching (return null to cancel) |
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 |
customStylesCallback | () => string | Inject custom CSS into Shadow DOM |
Callbacks Example
Rendering Callbacks
Customize how options, badges, and selected items are rendered:
| Property | Type | Description |
|---|---|---|
renderOptionContentCallback | (item: T, context: OptionContentRenderContext) => string | HTMLElement | Custom rendering for dropdown options |
renderBadgeContentCallback | (item: T, context: BadgeContentRenderContext) => string | HTMLElement | Custom rendering for selected item badges |
renderSelectedItemContentCallback | (item: T) => string | HTMLElement | Custom rendering for items in "more" popover |
getSelectedItemClassCallback | (item: T) => string | string[] | Get CSS classes for selected items in popover |
getCounterCallback | (count: number, moreCount?: number) => string | Custom counter text formatting |
Rendering Example
Tooltip Callbacks
Customize badge and remove button tooltips:
| Property | Type | Description |
|---|---|---|
getBadgeTooltipCallback | (item: T) => string | HTMLElement | Custom tooltip content for badges |
getRemoveButtonTooltipCallback | (item: T) => string | Custom tooltip for remove button |
Action Buttons
Configure action buttons in the dropdown:
| Property | Type | Description |
|---|---|---|
actionButtons | ActionButton<T>[] | Array of action button configurations |
Action Buttons 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