Badges Mode (Default)
Show selected items as removable badges
Live Demo
Pills show below the search input by default
Try It
Click X on each pill to remove selections individually.
Pills provide visual feedback and easy removal.
Mode
Badges Mode
display-mode="pills"
Default mode showing removable badges for each selected item.
Best for visual representation.
Count Mode + Badge
Count pill and badge (both options enabled)
Live Demo
Shows count pill (clickable) + counter next to toggle icon
Try It
This example shows both count features enabled:
- Count pill: Clickable "X selected" in input area
- Count badge: [X] next to dropdown toggle
You can use both together or separately (see examples below).
Mode
Combined Count Display
badges-display-mode="count"
show-counter="true"
Both options work independently and can be combined for maximum visibility.
Count Mode Only
Count pill without badge
Live Demo
Shows only the count pill (no badge)
Try It
Only the count pill is shown in the input area.
Click the count text to see selected items in a popover.
Use getCountBadgeCallback for i18n/pluralization.
Mode
Count Pill Only
badges-display-mode="count"
show-counter="false" (default)
Compact display best for limited space.
Counter Feature
Add [X] badge to any display mode
Live Demo
Pills mode with [X] badge added next to toggle icon
Try It
Important: The counter [X] is a supplementary feature, not a standalone display mode.
It can be added to any display mode (pills, count, or compact).
Badge provides quick visual feedback of total count, especially useful when pills scroll out of view.
Badge Info
Counter
show-counter="true"
Works with any pills-display-mode
Note: Cannot be used alone - must be combined with pills, count, or compact mode.
Compact Mode
First item + count in a single removable pill
Live Demo
Shows first item with count in a single pill
Try It
First selected item shown with count of remaining items in a single removable pill.
Example: [JavaScript (+2 more) | x]
Remove button clears ALL selections.
Click pill text to see all selected items in popover.
Automatically shows next item when selections change.
Mode
Compact Mode
badges-display-mode="compact"
Shows: JavaScript (+2 more)
Good balance between detail and space.
Uses getBadgeDisplayCallback for first item and getCountBadgeCallback for count text.
None Mode (Minimal Display)
No display in pills area - use with counter
Live Demo
Nothing shown in pills area - only [X] badge visible
Try It
Most compact display possible - no pills or count text shown.
Typically combined with show-counter="true" to show [X] indicator.
Click the counter to see all selected items in popover.
Or open the dropdown to see selections.
Mode
None Mode
badges-display-mode="none"
show-counter="true"
Perfect for extremely space-constrained layouts.
Pills container is empty and hidden via CSS.
Note: No callbacks are invoked in this mode (no display to render).
Pills Position: Top
Place pills above the search input
Live Demo
Pills appear above the input
Try It
Pills shown above input field.
Useful for certain UI layouts.
Position
Pills Position
badges-position="top"
Other options: bottom, left, right
Default: bottom
Pills Position: Left
Place pills to the left of the input
Live Demo
Pills appear inline to the left
Try It
Pills shown inline to the left of input.
Creates horizontal layout.
Position
Inline Position
badges-position="left"
Pills flow horizontally with input.
Requires sufficient width.
Pills Threshold
Auto-switch to count mode after threshold
Live Demo
Switches to count mode after 3 selections
Try It
Select more than 3 items to see automatic switch to count mode.
Combines benefits of both modes.
Threshold
Smart Threshold
badges-threshold="3"
Shows pills up to threshold, then switches to count.
Optimal UX for varying selection sizes.
🔧 Callback Behavior by Display Mode
Understanding when your callbacks are invoked is critical for proper implementation.
getBadgeDisplayCallback(item)
Controls the text shown for individual selected items.
| Display Mode | When Called | Example |
|---|---|---|
pills | ✅ For EACH selected item | Called 5 times for 5 selections |
partial | ✅ For EACH visible pill only | Called 3 times (shows "Item1", "Item2", "Item3" + "+2 more") |
compact | ✅ For ONLY the first item | Called 1 time (shows "Item1 (+4 more)") |
count | ❌ NOT called | No individual items shown |
none | ❌ NOT called | No display |
💡 Tip: Use this callback to show different text in pills vs dropdown (e.g., "John Doe" in pill, full details in dropdown)
getCountBadgeCallback(count, moreCount?)
Controls count text display. Signature: (count: number, moreCount?: number) => string
| Display Mode | When Called | Parameters | Example Output |
|---|---|---|---|
pills | ❌ NOT called | - | No count text |
partial | ✅ For "+X more" badge | count=5, moreCount=2 | "+2 more" |
compact | ✅ For "(+X more)" text | count=5, moreCount=4 | "(+4 more)" |
count | ✅ For main count text | count=5, moreCount=undefined | "5 selected" |
none | ❌ NOT called | - | No display |
💡 Tip: Check if moreCount is defined to handle both use cases:
getCountBadgeCallback: (count, moreCount) => {
if (moreCount !== undefined) {
return `+${moreCount} more`; // Partial/Compact mode
}
return `${count} selected`; // Count mode
}Counter [X] (Independent Feature)
- Always shows: Just the number in brackets
[5] - NOT affected by any callbacks
- Works with ALL display modes (including 'none')
- Controlled by:
show-counter="true"attribute
Quick Reference: What's Displayed
| Mode | Pills Area Shows | Callbacks Used |
|---|---|---|
pills | Individual pills for all items | getBadgeDisplayCallback (each item) |
partial | First N pills + "+X more" badge | getBadgeDisplayCallback (visible items), getCountBadgeCallback (badge) |
compact | Single pill: "FirstItem (+X more)" | getBadgeDisplayCallback (1st item), getCountBadgeCallback (count) |
count | "X selected" text + clear button | getCountBadgeCallback (text) |
none | Nothing (empty) | None |
badge [X] | Always shows [count] next to toggle | None (just shows number) |
Display Mode Configuration
| Attribute | Values | Default | Description |
|---|---|---|---|
badges-display-mode | badges | count | compact | partial | none | badges | How to display selected items. compact: first item + count in single pill. none: no display (use with counter). |
badges-position | top | bottom | left | right | bottom | Where to place pills relative to input |
badges-threshold | number | null | Auto-switch to count after N selections |
getCountBadgeCallback | (count: number, moreCount?: number) => string | (count, more?) => more ? `+${more} more` : `${count} selected` | Callback for count pill text (i18n/pluralization). Used for both count mode and partial mode "+X more" badge. |
show-counter | true | false | false | Show badge next to toggle icon |
📐 Display Tips
- Badges Mode: Best for visual representation and easy removal of selections
- Count Mode: Best when space is limited or many items are selected
- Compact Mode: Good compromise showing first item plus count
- Threshold: Combine pills and count modes for optimal UX
- Position: Adjust pills position based on your layout requirements