A Filter Pill offers a button paired with a popover to show and manage filtering options, the label and content of the filter can be handled through slots and props.
v-model expects an array of { name, active? } objects. The pill is "active" when any item has active: true.
The default scoped slot overrides the pill label and receives: { label, filters, activeFilters, activeFilterList, activeFilterOverflow }.
The content slot overrides the popover body, replacing the default checkbox list with custom content (e.g., radio groups).
In-place mutation: The pill copies the modelValue array at mount. To keep active state in sync, mutate objects with forEach rather than replacing the array with map.
Do
Use to filter a list, table, or other data set by a specific attribute (e.g., channel, contact center, date range).
Use the default checkbox popover for multi-select filters where several options can be active at once.
Use use-dropdown for single-select filters where only one option applies at a time (e.g., conversation type).
Provide end-tooltip-text on the clear button so it has an accessible name for screen readers.
Don’t
Don't use as a general-purpose action button — filter pills are for narrowing data, not triggering commands.
Don't use for binary on/off settings — use a Toggle.
Don't omit label and the default slot — the pill must always have visible text identifying the filter category.
Don't replace the array with map when toggling active state — mutate objects in-place with forEach to keep the pill's internal copy in sync.
Setting defer-selection holds checkbox changes in a pending state until Apply is clicked.
Cancel, Escape, or clicking outside discards pending changes.
Setting use-dropdown switches the overlay from a popover to a dropdown with keyboard-navigable
list items. This provides arrow key navigation, highlight management, and Enter/Space selection
out of the box — ideal for single-select filter patterns.
Combining the default and content slots with a radio group creates a single-select filter.
The label updates to show the selected option, and a clear button resets to the default.
Using the content slot, you can override the popover content with custom markup.
<dt-filter-pill:model-value="[{name: 'Contains'}, {name: 'Starts with'}]"label="Keyword"><template#content>
Enter a keyword to filter results
</template></dt-filter-pill>
Filter Pill popover content renders outside the DOM tree. Use the contentMode prop to apply color mode (invert, light, dark) to the positioned content. See Positioned Components for details.
Allows you to override the popover content, only use this if you need custom behavior
default
Allows you to customize the label slot
footerContent
Allows you to customize the popover footer. Receives { close, apply, cancel } bindings.
headerContent
Allows you to customize the popover header
startIcon
Icon displayed before the label
Props
Name
Default
Type
contentMode
"light"
|
"dark"
|
"invert"
Applies a color mode to the positioned content element.
deferSelection
false
boolean
When true, checkbox changes are held in a pending state until the user
clicks Apply. Cancel or closing the popover discards pending changes.
Only applies to popover mode (not useDropdown).
disabled
false
boolean
HTML disabled attribute
dropdownListClass
''
string|array|object
Additional CSS class(es) applied to the dropdown list wrapper.
Only applies when useDropdown is true.
endTooltipText
''
string
Text shown in tooltip when you hover the end button,
required as it is an icon only button
label
string
Label of the button
labelClass
''
string|array|object
Additional CSS class(es) applied to the label wrapper element.
modelValue
[]
array
Array of filters to display in the popover,
should be an array of objects with name and active properties
popoverAppendTo
'body'
"body"
|
"parent"
|
"root"
|
"HTMLElement"
Sets the element to which the
popover component
is going to append to
popoverContentClass
''
string|array|object
Additional CSS class(es) applied to the popover content area.
Only applies when useDropdown is false.
popoverDialogClass
''
string|array|object
Additional CSS class(es) applied to the popover dialog element.
Only applies when useDropdown is false.
If the dropdown does not fit in the direction described by "popoverPlacement",
it will attempt to change it's direction to the "popoverFallbackPlacements".
popoverFooterClass
''
string|array|object
Additional CSS class(es) applied to the outer popover footer element (d-popover__footer).
Only applies when useDropdown is false.
popoverHeaderClass
''
string|array|object
Additional CSS class(es) applied to the outer popover header element (d-popover__header).
Only applies when useDropdown is false.
popoverMaxHeight
''
string
Determines maximum height for the popover before overflow.
Possible units rem|px|em
popoverMaxWidth
''
string
Determines maximum width for the popover before overflow.
Possible units rem|px|%|em
The direction the popover displays relative to the anchor.
Tippy.js docs
readOnly
false
boolean
When true, the pill cannot be interacted with but does not
receive disabled visual styling. Adds d-filter-pill--read-only
class and hides the chevron icon. The clear button is suppressed
and the tooltip falls back to a read-only message when
startTooltipText is not provided.
showClear
true
"true"
|
"false"
Shows the clear button when a filter is active
size
200
"100"
|
"200"
|
"300"
|
"400"
|
"500"
The size of the button.
startTooltipText
''
string
Text shown in tooltip when you hover the start button,
required if no content is passed to default slot
useDropdown
false
boolean
When true, uses DtDropdown instead of DtPopover as the overlay.
Provides keyboard navigation (arrow keys) for list items.
Default content renders DtListItem elements (single-select)
instead of checkboxes (multi-select).
The primary button uses aria-disabled="true" in read-only mode instead of disabled, preserving focusability while indicating the control is not interactive.
The checkbox group inside the popover receives aria-label set to the pill's label prop, giving screen readers context for the list of options.
The clear button uses aria-label set to endTooltipText (or a localized default), ensuring the icon-only button has an accessible name.
Always provide a label prop or populate the default slot so the pill has visible text.
When active filters change the visible label (e.g., radio selection patterns), set start-tooltip-text to the original label so the full context remains available on hover and to assistive technology.
Provide end-tooltip-text for the clear button to give it a meaningful accessible name (e.g., "Remove filter").