Member Properties
Map object properties to component features using member attributes:
| Attribute | Type | Default | Description |
|---|---|---|---|
value-member | string | - | Property name for extracting unique ID/value from items |
display-value-member | string | - | Property name for extracting display text from items |
search-value-member | string | - | Property name for extracting searchable text from items |
icon-member | string | - | Property name for extracting icon/emoji from items |
subtitle-member | string | - | Property name for extracting subtitle/description from items |
group-member | string | - | Property name for extracting group name from items |
disabled-member | string | - | Property name for determining if item is disabled |
Value Formatting
Control how selected values are serialized:
| Attribute | Type | Default | Description |
|---|---|---|---|
value-format | 'json' | 'csv' | 'array' | 'json' | Format for serializing selected values. See Value Format examples |
Note: The getValueFormatCallback property (not HTML attribute) allows custom serialization logic.
Form Integration
Configure HTML form integration with hidden inputs:
| Attribute | Type | Default | Description |
|---|---|---|---|
name | string | - | HTML form field name for hidden input(s). See Form Integration examples |
Hidden inputs are created automatically and use the format specified by value-format.
Boolean Options
Enable or disable features:
| Attribute | Type | Default | Description |
|---|---|---|---|
multiple | boolean | true | Allow multiple selections |
enable-search | boolean | true | Enable search/filtering functionality |
allow-groups | boolean | true | Enable grouping of options |
show-checkboxes | boolean | true | Show checkboxes next to options |
sticky-actions | boolean | true | Keep action buttons fixed at top of dropdown |
close-on-select | boolean | false | Close dropdown after selecting an option |
lock-placement | boolean | true | Lock dropdown placement after first open |
allow-add-new | boolean | false | Allow adding new options not in the list |
show-counter | boolean | false | Show counter next to toggle icon |
keep-options-on-search | boolean | false | Keep all options visible during search (used with search-mode='navigate') |
should-keep-search-on-close | boolean | false | Keep search text when closing dropdown |
enable-badge-tooltips | boolean | false | Enable tooltips on selected item badges. See Advanced Features |
show-debug-info | boolean | false | Display debug information panel showing component state (development tool) |
Text Options
Customize text labels and messages:
| Attribute | Type | Default | Description |
|---|---|---|---|
search-placeholder | string | 'Search...' | Placeholder text for search input |
search-hint | string | - | Hint text shown above input when focused |
empty-message | string | 'No results found' | Message shown when no results found |
loading-message | string | 'Loading...' | Message shown while loading async data |
Note: For count text formatting with i18n/pluralization, use the getCounterCallback property (JavaScript callback: (count: number, moreCount?: number) => string). When moreCount is provided, it's for the "+X more" badge in partial mode.
Display Options
Control visual appearance and layout:
| Attribute | Type | Default | Description |
|---|---|---|---|
badges-display-mode | 'badges' | 'count' | 'compact' | 'partial' | 'none' | 'badges' | How to display selected items in the badges area |
badges-position | 'top' | 'bottom' | 'left' | 'right' | 'bottom' | Where to place badges relative to input |
badges-threshold | number | null | Trigger threshold mode after N selections |
badges-threshold-mode | 'count' | 'partial' | 'count' | Behavior when threshold exceeded: 'count' shows counter, 'partial' shows limited badges + more indicator. See Advanced Features |
badges-max-visible | number | 3 | Maximum badges to show in partial mode (used with badges-threshold-mode='partial') |
badge-tooltip-placement | 'top' | 'bottom' | 'left' | 'right' | 'top' | Tooltip placement relative to badge (requires enable-badge-tooltips="true") |
remove-button-tooltip-text | string | 'Remove' | Tooltip text for badge remove button |
search-input-mode | 'normal' | 'readonly' | 'hidden' | 'normal' | Search input display mode |
search-mode | 'filter' | 'navigate' | 'filter' | Search behavior: 'filter' hides non-matching, 'navigate' keeps all visible and jumps to matches |
actions-layout | 'nowrap' | 'wrap' | 'nowrap' | Action buttons layout: 'nowrap' single row, 'wrap' allows multiple rows |
Sizing Options
Control dimensions and limits:
| Attribute | Type | Default | Description |
|---|---|---|---|
dropdown-min-width | string (CSS value) | - | Minimum width for dropdown (e.g., '20rem', '300px') |
dropdown-max-width | string (CSS value) | - | Maximum width for dropdown (e.g., '30rem', '500px') |
max-height | string (CSS value) | '20rem' | Maximum height for dropdown options list |
min-search-length | number | 0 | Minimum characters required before loading data |
Note: For input sizing, use CSS classes (ms__input--xs, --sm, --md, --lg, --xl) or the --ms-rem CSS variable. See Custom Styling.
Virtual Scrolling
Optimize performance for large datasets:
| Attribute | Type | Default | Description |
|---|---|---|---|
enable-virtual-scroll | boolean | false | Enable virtual scrolling for better performance with large lists |
virtual-scroll-threshold | number | 100 | Number of items that triggers automatic virtual scrolling |
option-height | number | 40 | Fixed height (px) of each option for virtual scroll calculations |
badge-height | number | 28 | Fixed height (px) of each badge for virtual scroll in popover |
virtual-scroll-buffer | number | 5 | Number of extra items to render above/below visible area |
Virtual scrolling only renders visible items, dramatically improving performance for lists with thousands of options. See Virtual Scrolling.
Initial Values
Set default selected values:
| Attribute | Type | Default | Description |
|---|---|---|---|
initial-values | string (JSON array) | - | Initial selected values as JSON array (e.g., '[1,2,3]') |
💡 Usage Tips
- Boolean Attributes: Set to "false" to disable (e.g.,
multiple="false") - Kebab-case: All attributes use kebab-case in HTML (e.g.,
pills-display-mode) - Member vs Callback: Use member attributes for simple property mapping, callbacks for complex logic
- Initial Values: Must be valid JSON array when using
initial-valuesattribute - CSS Values: Sizing attributes accept any valid CSS unit (px, rem, em, %, etc.)