A dropdown input for selecting multiple values from a list of options. Supports field mapping to adapt to any data shape, grouped options, tag-style display with configurable overflow, and fully customizable option rendering via snippets.
Basic Example
Pass an array of objects with text and optionally value fields. Bind value to track the selected values as an array. Selected items appear as tags in the
trigger button.
Field Mapping
Your data rarely matches the component's default field names (text, value). Use the fields prop to remap without transforming your data.
Grouped Items
Items with a children array are rendered as labelled option groups with a visual divider
between groups. Only leaf items (children) are selectable — group headers are presentational.
Tags Display
Selected items are shown as tags in the trigger button. Use the maxDisplay prop to
limit how many tags are visible — additional selections show as a +N more badge. This keeps the trigger compact when many items are selected.
Props
- items: Array of objects or grouped option arrays
- fields: Remap your data keys to component fields
- value (bindable): Array of selected values
- selected (bindable): Array of selected raw item objects
- placeholder: Text shown when nothing is selected
- size: Size variant (
sm,md,lg) - maxDisplay: Max tags shown before "+N more" overflow badge
- align: Dropdown alignment (
start,end) - direction: Dropdown direction (
down,up) - disabled: Disable the entire multi-select
- class: Additional CSS classes on the root element
Snippets
- itemContent(proxy): Custom rendering for dropdown options
- groupContent(proxy): Custom rendering for group headers
ProxyItem API
Snippets receive a ProxyItem instance:
- proxy.label: Mapped display text
- proxy.icon: Mapped icon class
- proxy.value: The extracted value field (primitive)
- proxy.disabled: Whether the item is disabled
- proxy.get('field'): Read any field by mapped or raw name
Events
- onchange(values, items): Fired when selection changes — receives the array of selected values and the array of selected raw item objects