Attributes accept string values (booleans as
"true"/"false"). Object,
array and callback values (options, actionButtons, render*) are set as
JS properties on the element β see Callbacks and Methods.Data members
Tell the component which property of each option holds the value, label, icon, etc. Each has a callback counterpart (see Callbacks).
| Attribute | Type | Default | Description |
|---|---|---|---|
value-member | string | β | Property used as the option value / id. |
display-value-member | string | β | Property used as the visible label. |
search-value-member | string | β | Property matched against while searching. |
icon-member | string | β | Property holding an icon (emoji, glyph or markup). |
subtitle-member | string | β | Property holding a secondary line under the label. |
full-title-member | string | β | Property with a long / full title, shown on badges when show-badge-full-title is on. |
group-member | string | β | Property used to group options under headers. |
disabled-member | string | β | Property that marks an option disabled. |
Tree members
Enabling any path source turns on tree mode. See the Tree page.
| Attribute | Type | Default | Description |
|---|---|---|---|
path-member v2.0.0 | string | β | Materialized dot-path per node (e.g. "1.2.3"). Enables tree mode. |
parent-path-member v2.0.0 | string | β | Property holding the parent path. |
level-member v2.0.0 | string | β | Property holding the depth level. |
has-children-member v2.0.0 | string | β | Property flagging nodes that have children. |
is-selectable-member v2.0.0 | string | β | Property marking a node selectable (false = no checkbox, skipped by keyboard). |
tree-path-separator v2.0.0 | string | . | Separator between path segments. |
checkbox-mode v2.0.0 | 'independent' | 'cascade' | cascade | Whether checking a node cascades to its subtree. v2.2.0: now defaults to cascade (was independent) β checking a branch selects its whole subtree and branches render tristate. Set independent to keep per-node toggling. See the migration notes. |
cascade-select-policy v2.0.0 | 'rolled-up' | 'leaves' | 'all' | rolled-up | In cascade mode, which values are emitted. |
Selection & behavior
| Attribute | Type | Default | Description |
|---|---|---|---|
multiple | boolean | true | Allow selecting more than one option. |
allow-groups | boolean | true | Enable grouping by group-member. |
show-checkboxes | boolean | true | Show checkboxes in the option rows. |
close-on-select | boolean | false | Close the dropdown after each selection. |
checkbox-align | 'top' | 'center' | 'bottom' | center | Vertical alignment of the checkbox in tall rows. |
allow-add-new v2.0.0 | boolean | false | Show an βAdd β¦β prompt when a search yields no matches. |
overlay-group v2.0.0 | string | β | Coordinate βone overlay open at a timeβ across components sharing the group name. |
group-select-mode v2.2.0 | 'none' | 'cascade' | none | In a flat (non-tree), multi-select, grouped list, cascade puts a tristate select-all checkbox on each group header β it checks/unchecks that groupβs visible members and reads indeterminate when partial. The group name is never a value (getValue() / badges / form carry member values only). No effect in tree mode (use checkbox-mode) or single-select. |
prune-missing-selection v2.4.0 | boolean | false | When the options list is replaced, drop any selected value whose option is no longer present. Off by default β a selection that leaves the list is kept (still in getValue() and shown as a badge), which is right for search / paged lists where an item can leave the current page yet stay valid. Turn it on when a list replacement means the domain itself changed (e.g. an item deleted server-side); pruning is silent (no change). |
reserve-icon-slot v2.5.0 | boolean | false | Reserve a fixed-width icon gutter on every option row, including icon-less ones, so labels line up in a single start column when a list mixes rows with and without an icon (icon-member / getIconCallback). Off by default (icon-less rows get no gutter). Option-level β identical on flat lists and trees. The slot reuses --ms-option-icon-size and --ms-option-content-gap. |
Search
| Attribute | Type | Default | Description |
|---|---|---|---|
enable-search | boolean | true | Show the search input. |
search-mode | 'filter' | 'navigate' | filter | Filter hides non-matches; navigate keeps all rows and jumps between matches. |
search-input-mode | 'normal' | 'readonly' | 'hidden' | normal | Editable, read-only, or no search field. |
show-search-mode-toggle v2.0.0 | boolean | false | Show a filter/navigate toggle inside the fullscreen overlay. |
min-search-length | number | 0 | Minimum characters before search fires. |
search-debounce | number (ms) | 0 | Debounce delay for the async searchCallback. |
keep-options-on-search | boolean | true | Keep selected options visible while filtering. |
should-keep-search-on-close | boolean | true | Preserve the search term after closing. |
Display of selected items
| Attribute | Type | Default | Description |
|---|---|---|---|
badges-display-mode | 'badges' | 'count' | 'compact' | 'partial' | 'none' | badges | How selected items are represented. |
badges-position | 'top' | 'bottom' | 'left' | 'right' | bottom | Where the badge area sits relative to the input. |
badges-threshold | number | β | Collapse to count/partial once this many are selected. |
badges-threshold-mode | 'count' | 'partial' | count | How the threshold collapses badges. |
badges-max-visible | number | β | In partial mode, how many badges before β+X moreβ. |
collapse-badges-below v2.0.0 | number (px) | β | Force count mode when the controlβs own box is narrower than this β container-responsive, not viewport. |
show-counter | boolean | false | Show a selected-count indicator in the input. |
show-clear v2.0.0 | boolean | false | Show an inline β clear button inside the input. |
show-badge-full-title | boolean | false | Use the full title on badges. |
enable-selected-popover v2.0.0 | boolean | true | Allow the selected-items popover to open (set false when you render your own selection UI). |
selected-order v2.2.0 | 'as-selected' | 'label-asc' | 'label-desc' | 'member' | 'custom' | as-selected | Order of the selected items across badges, the partial β+N moreβ split (which items sit behind it), and the popover. Display-only β getValue(), form output and getSelected() always keep insertion order, and the dropdown is never reordered. member sorts by selected-order-member / getSelectedOrderCallback; custom uses selectedOrderCompareCallback. |
selected-order-member v2.2.0 | string | β | Property used as the sort key when selected-order="member" β numeric keys sort numerically, everything else via a locale compare. Overridden by getSelectedOrderCallback. |
Placeholders & text
| Attribute | Type | Default | Description |
|---|---|---|---|
search-placeholder | string | Search... | Placeholder for the search field. |
select-placeholder | string | Pick an option... | Shown when nothing is selected / search disabled. |
empty-message | string | No results found | Shown when a search yields no matches. |
no-data-placeholder | string | β | Shown when there are no options at all. |
loading-message | string | Loading... | Shown while options are loading. |
search-hint | string | β | Small hint text under the search field. |
add-new-text v2.0.0 | string | Add "{value}" | Template for the add-new prompt; {value} is the typed text. |
add-new-pending-text v2.0.0 | string | Adding "{value}"β¦ | Template while an async addNewCallback runs. |
remove-button-tooltip-text | string | β | Format string for the badge remove tooltip; {0} = item name. |
selected-popover-title v2.5.0 | string | Selected Items ({count}) | Translatable header for the selected-items popover (also the selectedPopoverTitle property). {count} is replaced with the current selection count, so translators control both the wording and where the number sits β e.g. VybranΓ© poloΕΎky ({count}). |
labels v2.5.0 | MultiSelectLabels (property-only) | β | Partial i18n map for the componentβs ARIA labels and short UI strings β property-only (an object, not an attribute). Set only the keys you need; the rest fall back to English. {item} / {count} interpolate. Keys: close, clearSelection, clearAllSelections, clearSearch, showFullLabel, removeItem, removeHiddenItems, groupSelectedLabel, andMore, prevMatch, nextMatch. MultiSelectLabels is exported from the package entry. |
Form integration
| Attribute | Type | Default | Description |
|---|---|---|---|
name | string | β | Form field name for the auto-created hidden input(s). |
value-format | 'json' | 'csv' | 'array' | json | Serialization: ["a","b"], a,b, or repeated name[] inputs. |
initial-values | JSON array | CSV | β | Initial selection (element-only). Accepts ["a","b"] or a,b. |
Declarative data (element-only)
| Attribute | Type | Default | Description |
|---|---|---|---|
data-options | string | β | Option data as an attribute, parsed per data-options-format. |
data-options-format | 'json' | 'csv' | 'plain' | json | How data-options is parsed. |
data-options-splitter | string | , | Field delimiter for CSV/plain (supports \t \n \r). |
data-options-row-splitter | string | newline | Row delimiter for CSV/plain. |
Responsive & presentation
| Attribute | Type | Default | Description |
|---|---|---|---|
mobile-presentation v2.0.0 | 'auto' | 'floating' | 'fullscreen' | auto | Anchored dropdown vs full-screen sheet (element-only). |
fullscreen-autofocus | boolean | false | Focus the search field when the fullscreen sheet opens. |
lock-placement | boolean | true | Lock the dropdown placement after first open. |
dropdown-min-width | CSS length | β | Minimum dropdown width. |
dropdown-max-width | CSS length | β | Maximum dropdown width. |
dropdown-width | CSS length | β | Sugar for --ms-dropdown-width (element-only). |
max-height | CSS length | 20rem | Max dropdown height before scrolling. |
selected-popover-width v2.0.0 | CSS length | β | Fixed popover width. Defaults to the field width. |
Virtual scrolling
| Attribute | Type | Default | Description |
|---|---|---|---|
enable-virtual-scroll | boolean | false | Force virtual scrolling on. |
virtual-scroll-threshold | number | 100 | Option count that auto-enables virtual scrolling. |
option-height | number (px) | 50 | Fixed row height used by virtual scroll. |
badge-height | number (px) | 36 | Fixed badge height for popover virtual scroll. |
virtual-scroll-buffer | number | 10 | Extra rows rendered above/below the viewport. |
Tooltips
| Attribute | Type | Default | Description |
|---|---|---|---|
enable-option-tooltips | boolean | false | Enable tooltips on option rows. |
enable-badge-tooltips | boolean | false | Enable tooltips on badges. |
option-tooltip-placement | Placement | top-start | Floating-UI placement for option tooltips. |
badge-tooltip-placement | Placement | top | Floating-UI placement for badge tooltips. |
option-tooltip-follow-cursor | boolean | false | Option tooltip tracks the pointer. |
option-tooltip-delay / badge-tooltip-delay | number (ms) | 100 | Show delay. |
option-tooltip-offset / badge-tooltip-offset | number (px) | 8 | Gap between anchor and tooltip. |
Action bar
| Attribute | Type | Default | Description |
|---|---|---|---|
actions-position | 'top' | 'bottom' | top | Where the action-button bar sits in the dropdown. |
actions-layout | 'nowrap' | 'wrap' | nowrap | Whether buttons wrap onto new rows. |
actions-align | 'stretch' | 'left' | 'right' | 'center' | 'space-between' | stretch | Horizontal alignment of the buttons. |
sticky-actions | boolean | true | Keep the action bar pinned while the list scrolls. |
Styling
| Attribute | Type | Default | Description |
|---|---|---|---|
custom-styles v2.2.0 | string (CSS) | β | Raw CSS injected verbatim β selectors and all β into a replaceable style slot at the top of the shadow root. The declarative, no-JavaScript twin of customStylesCallback (which still wins when both are set), so static HTML / server-rendered / no-build pages can restyle shadow-DOM internals (.ms__badge, .ms__option, β¦) and their own custom-rendered content. Mirrored by the customStyles property and reactive β changing or removing it re-applies or clears the slot. |
Lifecycle
| Attribute | Type | Default | Description |
|---|---|---|---|
defer v2.1.0 | boolean | false | Hold the first render. When present the component builds nothing on upgrade (reserves space only) β wire options, callbacks (e.g. customStylesCallback) and listeners first, then release with ready() (or by removing the attribute) so it builds once, flash-free. Latched; reflects an is-ready attribute after building. CSS hook: :host([defer]:not([is-ready])). |