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 |
allow-select-all | boolean | true | Show 'Select All' button |
allow-clear-all | boolean | true | Show 'Clear All' button |
show-checkboxes | boolean | true | Show checkboxes next to options |
sticky-actions | boolean | true | Keep Select All/Clear All buttons fixed at top |
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 |
enable-pill-tooltips | boolean | false | Enable tooltips on selected item pills. 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 getCountBadgeCallback 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 |
|---|---|---|---|
pills-display-mode | 'pills' | 'count' | 'compact' | 'pills' | How to display selected items in the pills area |
pills-position | 'top' | 'bottom' | 'left' | 'right' | 'bottom' | Where to place pills relative to input |
pills-threshold | number | null | Trigger threshold mode after N selections |
pills-threshold-mode | 'count' | 'partial' | 'count' | Behavior when threshold exceeded: 'count' shows counter, 'partial' shows limited pills + more badge. See Advanced Features |
pills-max-visible | number | 3 | Maximum pills to show in partial mode (used with pills-threshold-mode='partial') |
pill-tooltip-placement | 'top' | 'bottom' | 'left' | 'right' | 'top' | Tooltip placement relative to pill (requires enable-pill-tooltips="true") |
pill-tooltip-delay | number | 300 | Delay in milliseconds before showing tooltip (requires enable-pill-tooltips="true") |
pill-tooltip-offset | number | 8 | Distance in pixels between pill and tooltip (requires enable-pill-tooltips="true") |
search-input-mode | 'normal' | 'readonly' | 'hidden' | 'normal' | Search input display mode |
Sizing Options
Control dimensions and limits:
| Attribute | Type | Default | Description |
|---|---|---|---|
dropdown-min-width | string (CSS value) | - | Minimum width for dropdown (e.g., '20rem', '300px') |
max-height | string (CSS value) | '20rem' | Maximum height for dropdown |
min-search-length | number | 0 | Minimum characters required before loading data |
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.)