Filter chip

A filter chip turns one filter on or off and shows the state with a check mark. Make it removable when readers should be able to drop a filter from the row entirely. Press a few of the recipe filters below and watch the check marks arrive.

Vegetarian Under 30 minutes Gluten-free Vegan High protein One pan Dairy-free Spicy Make ahead Nut-free Budget Kid-friendly Air fryer Soups Breakfast Dessert Freezer meals Weeknight 5 ingredients No-bake Low carb Grilling Salads Pasta Slow cooker

Reference docs⁠

BlazorReactWebOverviewExamplesAPIStylingAccessibility

Choosing a chip⁠

Four chips share one shape. Each suits a different job:

  • Assist chip: a smart, related action offered in context, such as Add to calendar beside an event.
  • Suggestion chip: a generated reply or query the reader can take, such as a suggested answer in a chat.
  • Filter chip: a tag that turns a filter on or off, such as Vegetarian or Under 30 minutes.
  • Input chip: one piece of information the reader entered, removable, such as a recipient in an address line.

Two jobs belong elsewhere. An action on the page's own content is a button, and a choice in a form is a checkbox, radio button, or select. Each chip has a set of its own that lays a group of them out.

Choosing a variant⁠

Two variants set how much a chip stands out, from most to least:

  • Elevated: a raised container for chips that sit on a patterned or photographic surface, such as a filter row over a recipe photo.
  • Outlined: the default, for chips on a plain surface, such as a filter row above a list of recipes.

Chips and sets⁠

A filter chip is one filter, and a filter chip set is the group of filters it sits in. Each does a job the other cannot:

  • The chip holds one filter: its label, its icon, and whether it is on. It stands alone where a screen offers a single filter, such as Open now above a map.
  • The set makes several chips one control. It lays them out in rows that wrap, takes one Tab stop for the whole group with the arrow keys moving between chips, and tells a screen reader the chips belong together under the name in its aria-label.

Loose chips each take a Tab stop of their own, so a keyboard user presses Tab once per filter to get past them. A screen reader hears them as unrelated buttons. Put any group of filter chips in a set. The set leaves selection to its chips, so each keeps its own selected and any number can be on at once.

A set lays out its own kind of chip only. Any other child stays where it is but is left out of the arrow-key movement, and the set logs a warning naming it.

Built in⁠

  • A check mark replaces the leading icon while selected is set, and the selected-icon slot swaps in your own.
  • A trailing remove button, switched on by removable, takes the chip off the page when it is clicked.
  • badge-value and badge-dot add a count or a dot, with no separate badge element to place.
  • tooltip-value adds a tooltip that a screen reader also reads as the chip's description.
  • touch-target reaches at least 48 by 48 pixels, even though a small chip paints 32 pixels tall.
  • A removable chip's remove button is one arrow key away, so Tab stays on the filters.

Using filter chips well⁠

  • Label each chip with a short tag or descriptive word, such as Vegetarian, never a sentence.
  • Keep the primary action on a screen in a button, and leave the chips to refine content.
  • Put each group of filters in its own filter chip set, directly above the content it narrows, and give the set an aria-label that names the group.
  • Use a set of filter chips for choices a reader can combine; offer radio buttons or a select for exactly one choice.
  • Match the chip to the job: an assist chip for a related action, a suggestion chip for a generated reply, an input chip for something the reader entered.

These rules follow Material 3 Expressive's guidance for chips, on material.io.

Variants⁠

variant sets how a chip sits on its surface: outlined draws an outline, and elevated raises the container. Omit it and the chip takes the variant from your style configuration, which is outlined unless you have changed it. Choosing a variant says when each suits.

Size⁠

size takes one of two values, either small or extra-small. Omit it and the chip takes the size from your style configuration, which is small unless you have changed it.

touch-target sets the area that takes a touch. The default, overflow, extends it to at least 48 by 48 pixels without growing the chip. Choose wrapper when the layout should reserve that space, and none to keep the touch target at the chip's painted size.

Icons⁠

Give a chip a leading icon by name with icon-name, or put a cw-icon in the icon slot, which wins if both are set. A selected chip swaps the leading icon for a check mark. Supply your own with the selected-icon slot.

remove-trailing-icon-name and the remove-trailing-icon slot replace the built-in cross on a removable chip. flip-icon-in-rtl mirrors an icon from icon-name on a right-to-left page; slotted icons are not mirrored.

Badges⁠

badge-value puts a count or short text on the chip, such as the number of matching recipes. badge-dot shows a dot with no text, and badge-value is then ignored. badge-concealed hides the badge and keeps its settings, so clearing it shows the same badge again.

Tooltips⁠

tooltip-value adds a tooltip that opens on hover and on focus. It adds detail to the label and does not replace it. tooltip-position picks where the tooltip sits, from eight positions. Omit it and the chip takes the position from your style configuration, which is end-center unless you have changed it.

Selection⁠

A click toggles selected. Read the state from selected, or listen for change, which fires after a click and never when code sets selected. Flip a value from change to drive the list the chip filters.

Removing⁠

removable adds a trailing remove button. Clicking it fires remove, and the chip then removes itself from the page and from its set. A listener that calls preventDefault() keeps the chip, which suits a confirmation step. A framework that renders the chips from a list must also update that list in the listener, or the next render brings the chip back.

Disabled and soft-disabled⁠

disabled takes a chip out of the keyboard's reach: in a set, the arrow keys skip it. soft-disabled keeps the chip in the Tab order and blocks the toggle, which suits a filter that is unavailable for now but should still be discoverable. Both also stop the remove button.

In a set⁠

Every demo on this tab puts its chips in a cw-filter-chip-set, because that is how filters are used. Switch the set off below and press Tab: it visits every chip in turn. Switch it back on, and Tab reaches the group once while the arrow keys take over. Chips and sets says why both are needed.

change bubbles to the set from each chip, so one listener on the set hears every filter.

Wrapping⁠

A set lays its chips out in a row, wraps them onto new rows when the row is full, and leaves an 8-pixel gap between them. The first set below is long enough to wrap in a narrow preview.

Above results⁠

Place a set directly above the content it narrows, so the group and its effect read together.

Filter chip set Filter chip

Properties⁠

PropertyAttributeTypeDescription
compareWith(a: TItem, b: TItem) => booleanDecides whether two values name the same chip. When set, neither valueKey nor the default matching applies.
selectionModeselection-modeSelectionModedefault SelectionMode.MultiHow many chips can be selected. multi: any number, each chip on its own. single: at most one, and selecting a chip deselects the others. selection-required: exactly one once a chip is selected; clicking the selected chip leaves it selected.
valuevalueTItemThe selected chip's value, or null when no chip is selected. With several selected, the first of them. Setting it in a single mode selects the chip holding that value and deselects the others; in multi mode, set values instead, and a write here is ignored.
valueKeyvalue-keystringThe field that identifies an object value: two objects match when this field holds the same value on both.
valuesTItem[]The selected chips' values, in the order the chips appear. Setting it in multi mode selects exactly the chips holding those values; in a single mode, set value instead, and a write here is ignored.

Slots⁠

SlotDescription
(default)The cw-filter-chip elements, in the order they appear.

Only cw-filter-chip children take part in keyboard travel. Any other child stays where it is, outside the travel, and the set logs a warning naming it.

Events⁠

EventTypeDetailDescription
changeSelectionChangeEventSelectionChangeEventDetail<TItem>Dispatched after the selection changes, from a click or from a chip changing or leaving the set. It does not fire when code sets value or values. It bubbles.

Props⁠

PropTypeDescription
compareWith(a: TItem, b: TItem) => booleanDecides whether two values name the same chip. When set, neither valueKey nor the default matching applies.
selectionModeSelectionModeTypedefault SelectionMode.MultiHow many chips can be selected. multi: any number, each chip on its own. single: at most one, and selecting a chip deselects the others. selection-required: exactly one once a chip is selected; clicking the selected chip leaves it selected.
valueTItemThe selected chip's value, or null when no chip is selected. With several selected, the first of them. Setting it in a single mode selects the chip holding that value and deselects the others; in multi mode, set values instead, and a write here is ignored.
valueKeystringThe field that identifies an object value: two objects match when this field holds the same value on both.
valuesTItem[]The selected chips' values, in the order the chips appear. Setting it in multi mode selects exactly the chips holding those values; in a single mode, set value instead, and a write here is ignored.

Children⁠

ChildDescription
childrenThe CrFilterChip elements, in the order they appear.

Only cw-filter-chip children take part in keyboard travel. Any other child stays where it is, outside the travel, and the set logs a warning naming it.

Events⁠

PropArgumentDescription
onChangeSelectionChangeEvent<TItem>Dispatched after the selection changes, from a click or from a chip changing or leaving the set. It does not fire when code sets value or values. It bubbles. Its detail carries value and values.

Parameters⁠

ParameterTypeDescription
SelectionModeSelectionMode?default SelectionMode.MultiHow many chips can be selected. multi: any number, each chip on its own. single: at most one, and selecting a chip deselects the others. selection-required: exactly one once a chip is selected; clicking the selected chip leaves it selected.
ValueTItemThe selected chip's value, or null when no chip is selected. With several selected, the first of them. Setting it in a single mode selects the chip holding that value and deselects the others; in multi mode, set Values instead, and a write here is ignored.
ValueExpressionExpression<Func<TItem>>?Gets or sets an expression that identifies the bound value.
ValuesIList<TItem>The selected chips' values, in the order the chips appear. Setting it in multi mode selects exactly the chips holding those values; in a single mode, set Value instead, and a write here is ignored.
ValuesExpressionExpression<Func<IList<TItem>>>?Gets or sets an expression that identifies the bound value.

Render fragments⁠

ParameterTypeDescription
ChildContentRenderFragment?The CbFilterChip elements, in the order they appear.

Only cw-filter-chip children take part in keyboard travel. Any other child stays where it is, outside the travel, and the set logs a warning naming it.

Event callbacks⁠

ParameterTypeDescription
OnChangeEventCallback<SelectionChangeEventArgs<TItem>>Dispatched after the selection changes, from a click or from a chip changing or leaving the set. It does not fire when code sets Value or Values. It bubbles. Its detail carries Value and Values.

Inputs⁠

InputTypeDescription
compareWith(a: TItem, b: TItem) => booleanDecides whether two values name the same chip. When set, neither valueKey nor the default matching applies.
selectionModeSelectionModeTypedefault SelectionMode.MultiHow many chips can be selected. multi: any number, each chip on its own. single: at most one, and selecting a chip deselects the others. selection-required: exactly one once a chip is selected; clicking the selected chip leaves it selected.
valueTItemThe selected chip's value, or null when no chip is selected. With several selected, the first of them. Setting it in a single mode selects the chip holding that value and deselects the others; in multi mode, set values instead, and a write here is ignored.
valueKeystringThe field that identifies an object value: two objects match when this field holds the same value on both.
valuesTItem[]The selected chips' values, in the order the chips appear. Setting it in multi mode selects exactly the chips holding those values; in a single mode, set value instead, and a write here is ignored.

Content projection⁠

ContentDescription
content with no slotThe CaFilterChip elements, in the order they appear.

Only cw-filter-chip children take part in keyboard travel. Any other child stays where it is, outside the travel, and the set logs a warning naming it.

Outputs⁠

OutputEventDescription
cwChangeSelectionChangeEventDispatched after the selection changes, from a click or from a chip changing or leaving the set. It does not fire when code sets value or values. It bubbles. Its detail carries value and values.

Props⁠

PropTypeDescription
compareWith(a: TItem, b: TItem) => booleanDecides whether two values name the same chip. When set, neither valueKey nor the default matching applies.
selectionModeSelectionModeTypedefault SelectionMode.MultiHow many chips can be selected. multi: any number, each chip on its own. single: at most one, and selecting a chip deselects the others. selection-required: exactly one once a chip is selected; clicking the selected chip leaves it selected.
valueTItemThe selected chip's value, or null when no chip is selected. With several selected, the first of them. Setting it in a single mode selects the chip holding that value and deselects the others; in multi mode, set values instead, and a write here is ignored.
valueKeystringThe field that identifies an object value: two objects match when this field holds the same value on both.
valuesTItem[]The selected chips' values, in the order the chips appear. Setting it in multi mode selects exactly the chips holding those values; in a single mode, set value instead, and a write here is ignored.

Slots⁠

SlotDescription
defaultThe CvFilterChip elements, in the order they appear.

Only cw-filter-chip children take part in keyboard travel. Any other child stays where it is, outside the travel, and the set logs a warning naming it.

Events⁠

EventTypeDescription
changeSelectionChangeEventDispatched after the selection changes, from a click or from a chip changing or leaving the set. It does not fire when code sets value or values. It bubbles. Its detail carries value and values.

Props⁠

PropTypeDescription
compareWith(a: TItem, b: TItem) => booleanDecides whether two values name the same chip. When set, neither valueKey nor the default matching applies.
selectionModeSelectionModeTypedefault SelectionMode.MultiHow many chips can be selected. multi: any number, each chip on its own. single: at most one, and selecting a chip deselects the others. selection-required: exactly one once a chip is selected; clicking the selected chip leaves it selected.
valueTItemThe selected chip's value, or null when no chip is selected. With several selected, the first of them. Setting it in a single mode selects the chip holding that value and deselects the others; in multi mode, set values instead, and a write here is ignored.
valueKeystringThe field that identifies an object value: two objects match when this field holds the same value on both.
valuesTItem[]The selected chips' values, in the order the chips appear. Setting it in multi mode selects exactly the chips holding those values; in a single mode, set value instead, and a write here is ignored.

Snippets⁠

SnippetDescription
childrenThe CsFilterChip elements, in the order they appear.

Only cw-filter-chip children take part in keyboard travel. Any other child stays where it is, outside the travel, and the set logs a warning naming it.

Events⁠

PropTypeDescription
onChangeSelectionChangeEventDispatched after the selection changes, from a click or from a chip changing or leaving the set. It does not fire when code sets value or values. It bubbles. Its detail carries value and values.

Properties⁠

PropertyAttributeTypeDescription
badgeConcealedbadge-concealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbadge-dotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuebadge-valuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disableddisabledbooleandefault falseWhether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled.
flipIconInRtlflip-icon-in-rtlbooleandefault falseFlips the icons supplied by the icon-name and remove-trailing-icon-name properties in RTL mode. A slotted icon is not flipped. See Icons.
iconNameicon-namestringA Material Symbols icon name. This is an alternative to using the icon slot. If both are provided, the icon slot will take precedence, and a warning will be logged. See Icons.
removableremovablebooleandefault falseShows a remove button at the end of the chip. See Removing.
removeTrailingIconNameremove-trailing-icon-namestringA Material Symbols icon name. This is an alternative to using the remove-trailing-icon slot. If both are provided, the remove-trailing-icon slot will take precedence, and a warning will be logged. See Icons.
selectedselectedbooleandefault falseMarks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection.
sizesizesmall, extra-smallChipSizeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configurationSets how tall the chip is. See Size.
softDisabledsoft-disabledbooleandefault falseWhether or not the chip is "soft-disabled" (disabled but still focusable).A soft-disabled chip looks disabled and ignores clicks, but stays focusable. Use this when a chip needs increased visibility when disabled. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositiontooltip-positionstart-start, start-center, start-end, center-start, center-end, end-start, end-center, end-endTooltipPositionTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuetooltip-valuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargettouch-targetnone, overflow, wrapperTouchTargetTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationThe area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size.
valuevalueunknownThe chip's value: a filter chip set reports it as its own value or among its values while the chip is selected. Set from code it can be any value, such as a number or an object; the value attribute sets it to a string.
variantvariantelevated, outlinedChipVariantChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configurationSets whether the chip is raised with a shadow or flat with an outline. See Variants.

While disabled or soft-disabled is set, the remove button ignores clicks too.

Slots⁠

SlotDescription
(default)The chip's label content.
iconThe icon to display in the chip, intended for a cw-icon or similarly sized visual content such as an SVG.
selected-iconThe icon to display in place of the leading icon while the chip is selected, intended for a cw-icon or equivalent. The default is a check mark.
remove-trailing-iconThe icon on the remove button, intended for a cw-icon or equivalent. The default is a cross. Shown only while removable is set.

While selected is set, selected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name.

Events⁠

EventTypeDetailDescription
clickMouseEvent—Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable.
changeEvent—Dispatched after the chip's selected state changes: a click toggles it, or its filter chip set selects or deselects it. It does not fire when code sets selected. It bubbles.
removeEvent—Dispatched when the remove button is clicked. The chip then removes itself unless the event is canceled. It bubbles and is cancelable.

Calling preventDefault() on click reverts the toggle and suppresses change. A listener that does not cancel remove must also update the list that renders the chips. Neither change nor remove is composed, and a soft-disabled chip ignores clicks.

Props⁠

PropTypeDescription
badgeConcealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disabledbooleandefault falseWhether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled.
flipIconInRtlbooleandefault falseFlips the icons supplied by the iconName and removeTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons.
iconNamestringA Material Symbols icon name. This is an alternative to using the slot="icon" child. If both are provided, the slot="icon" child will take precedence, and a warning will be logged. See Icons.
removablebooleandefault falseShows a remove button at the end of the chip. See Removing.
removeTrailingIconNamestringA Material Symbols icon name. This is an alternative to using the slot="remove-trailing-icon" child. If both are provided, the slot="remove-trailing-icon" child will take precedence, and a warning will be logged. See Icons.
selectedbooleandefault falseMarks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection.
sizeChipSizeTypeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configurationSets how tall the chip is. See Size.
softDisabledbooleandefault falseWhether or not the chip is "soft-disabled" (disabled but still focusable).A soft-disabled chip looks disabled and ignores clicks, but stays focusable. Use this when a chip needs increased visibility when disabled. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargetTouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationThe area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size.
valueunknownThe chip's value: a filter chip set reports it as its own value or among its values while the chip is selected. Set from code it can be any value, such as a number or an object; the value attribute sets it to a string.
variantChipVariantTypeChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configurationSets whether the chip is raised with a shadow or flat with an outline. See Variants.

While disabled or soft-disabled is set, the remove button ignores clicks too.

Children⁠

ChildDescription
childrenThe chip's label content.
a child with slot="icon"The icon to display in the chip, intended for a CrIcon or similarly sized visual content such as an SVG.
a child with slot="selected-icon"The icon to display in place of the leading icon while the chip is selected, intended for a CrIcon or equivalent. The default is a check mark.
a child with slot="remove-trailing-icon"The icon on the remove button, intended for a CrIcon or equivalent. The default is a cross. Shown only while removable is set.

While selected is set, selected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name.

Events⁠

PropArgumentDescription
onClickReact.MouseEvent<HTMLElement>Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable.
onChangeReact.ChangeEvent<HTMLInputElement>Dispatched after the chip's selected state changes: a click toggles it, or its filter chip set selects or deselects it. It does not fire when code sets selected. It bubbles.
onRemoveEventDispatched when the remove button is clicked. The chip then removes itself unless the event is canceled. It bubbles and is cancelable.

Calling preventDefault() on click reverts the toggle and suppresses change. A listener that does not cancel remove must also update the list that renders the chips. Neither change nor remove is composed, and a soft-disabled chip ignores clicks.

Parameters⁠

ParameterTypeDescription
BadgeConcealedbool?default falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
BadgeDotbool?default falseShows the badge as a small dot with no text, whether or not BadgeValue is set. See Badges.
BadgeValuestring?The badge's text. While it is empty and BadgeDot is not set, no badge renders. Ignored if BadgeDot is set. See Badges.
Disabledbool?default falseWhether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled.
FlipIconInRtlbool?default falseFlips the icons supplied by the IconName and RemoveTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons.
IconNamestring?A Material Symbols icon name. This is an alternative to using the Icon render fragment. If both are provided, the Icon render fragment will take precedence, and a warning will be logged. See Icons.
Removablebool?default falseShows a remove button at the end of the chip. See Removing.
RemoveTrailingIconNamestring?A Material Symbols icon name. This is an alternative to using the RemoveTrailingIcon render fragment. If both are provided, the RemoveTrailingIcon render fragment will take precedence, and a warning will be logged. See Icons.
Selectedbooldefault falseMarks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection.
SelectedExpressionExpression<Func<bool>>?Gets or sets an expression that identifies the bound value.
SizeChipSize?ChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configurationSets how tall the chip is. See Size.
SoftDisabledbool?default falseWhether or not the chip is "soft-disabled" (disabled but still focusable).A soft-disabled chip looks disabled and ignores clicks, but stays focusable. Use this when a chip needs increased visibility when disabled. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
TooltipPositionTooltipPosition?TooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without TooltipValue. See Tooltips.
TooltipValuestring?The tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
TouchTargetTouchTarget?TouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationThe area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size.
ValueTItemThe chip's value: a filter chip set reports it as its own Value or among its values while the chip is selected. Set from code it can be any value, such as a number or an object; the Value attribute sets it to a string.
VariantChipVariant?ChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configurationSets whether the chip is raised with a shadow or flat with an outline. See Variants.

While disabled or soft-disabled is set, the remove button ignores clicks too.

Render fragments⁠

Once you write Icon or any other fragment as a child element, the main content must go in an explicit <ChildContent> too; markup beside <Icon> is a compile error. Here ChildContent is: The chip's label content.

<CbFilterChip>
    <Icon><CbIcon>favorite</CbIcon></Icon>
    <ChildContent>Main content</ChildContent>
</CbFilterChip>
content_copy
ParameterTypeDescription
ChildContentRenderFragment?The chip's label content.
IconRenderFragment?The icon to display in the chip, intended for a CbIcon or similarly sized visual content such as an SVG.
RemoveTrailingIconRenderFragment?The icon on the remove button, intended for a CbIcon or equivalent. The default is a cross. Shown only while Removable is set.
SelectedIconRenderFragment?The icon to display in place of the leading icon while the chip is selected, intended for a CbIcon or equivalent. The default is a check mark.

While selected is set, selected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name.

Event callbacks⁠

ParameterTypeDescription
OnClickEventCallback<MouseEventArgs>Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable.
OnChangeEventCallback<ChangeEventArgs>Dispatched after the chip's selected state changes: a click toggles it, or its filter chip set selects or deselects it. It does not fire when code sets Selected. It bubbles.
OnRemoveEventCallbackDispatched when the remove button is clicked. The chip then removes itself unless the event is canceled. It bubbles and is cancelable.

Calling preventDefault() on click reverts the toggle and suppresses change. A listener that does not cancel remove must also update the list that renders the chips. Neither change nor remove is composed, and a soft-disabled chip ignores clicks.

Inputs⁠

InputTypeDescription
badgeConcealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disabledbooleandefault falseWhether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled.
flipIconInRtlbooleandefault falseFlips the icons supplied by the iconName and removeTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons.
iconNamestringA Material Symbols icon name. This is an alternative to using the icon slot. If both are provided, the icon slot will take precedence, and a warning will be logged. See Icons.
removablebooleandefault falseShows a remove button at the end of the chip. See Removing.
removeTrailingIconNamestringA Material Symbols icon name. This is an alternative to using the remove-trailing-icon slot. If both are provided, the remove-trailing-icon slot will take precedence, and a warning will be logged. See Icons.
selectedbooleandefault falseMarks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection.
sizeChipSizeTypeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configurationSets how tall the chip is. See Size.
softDisabledbooleandefault falseWhether or not the chip is "soft-disabled" (disabled but still focusable).A soft-disabled chip looks disabled and ignores clicks, but stays focusable. Use this when a chip needs increased visibility when disabled. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargetTouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationThe area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size.
valueunknownThe chip's value: a filter chip set reports it as its own value or among its values while the chip is selected. Set from code it can be any value, such as a number or an object; the value attribute sets it to a string.
variantChipVariantTypeChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configurationSets whether the chip is raised with a shadow or flat with an outline. See Variants.

While disabled or soft-disabled is set, the remove button ignores clicks too.

Content projection⁠

ContentDescription
content with no slotThe chip's label content.
an element with slot="icon"The icon to display in the chip, intended for a CaIcon or similarly sized visual content such as an SVG.
an element with slot="selected-icon"The icon to display in place of the leading icon while the chip is selected, intended for a CaIcon or equivalent. The default is a check mark.
an element with slot="remove-trailing-icon"The icon on the remove button, intended for a CaIcon or equivalent. The default is a cross. Shown only while removable is set.

While selected is set, selected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name.

Outputs⁠

OutputEventDescription
cwClickMouseEventDispatched when the chip is clicked. It bubbles, is composed, and is cancelable.
cwChangeEventDispatched after the chip's selected state changes: a click toggles it, or its filter chip set selects or deselects it. It does not fire when code sets selected. It bubbles.
cwRemoveEventDispatched when the remove button is clicked. The chip then removes itself unless the event is canceled. It bubbles and is cancelable.

Calling preventDefault() on click reverts the toggle and suppresses change. A listener that does not cancel remove must also update the list that renders the chips. Neither change nor remove is composed, and a soft-disabled chip ignores clicks.

Props⁠

PropTypeDescription
badgeConcealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disabledbooleandefault falseWhether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled.
flipIconInRtlbooleandefault falseFlips the icons supplied by the iconName and removeTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons.
iconNamestringA Material Symbols icon name. This is an alternative to using the icon slot. If both are provided, the icon slot will take precedence, and a warning will be logged. See Icons.
removablebooleandefault falseShows a remove button at the end of the chip. See Removing.
removeTrailingIconNamestringA Material Symbols icon name. This is an alternative to using the remove-trailing-icon slot. If both are provided, the remove-trailing-icon slot will take precedence, and a warning will be logged. See Icons.
selectedbooleandefault falseMarks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection.
sizeChipSizeTypeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configurationSets how tall the chip is. See Size.
softDisabledbooleandefault falseWhether or not the chip is "soft-disabled" (disabled but still focusable).A soft-disabled chip looks disabled and ignores clicks, but stays focusable. Use this when a chip needs increased visibility when disabled. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargetTouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationThe area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size.
valueunknownThe chip's value: a filter chip set reports it as its own value or among its values while the chip is selected. Set from code it can be any value, such as a number or an object; the value attribute sets it to a string.
variantChipVariantTypeChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configurationSets whether the chip is raised with a shadow or flat with an outline. See Variants.

While disabled or soft-disabled is set, the remove button ignores clicks too.

Slots⁠

SlotDescription
defaultThe chip's label content.
iconThe icon to display in the chip, intended for a CvIcon or similarly sized visual content such as an SVG.
remove-trailing-iconThe icon on the remove button, intended for a CvIcon or equivalent. The default is a cross. Shown only while removable is set.
selected-iconThe icon to display in place of the leading icon while the chip is selected, intended for a CvIcon or equivalent. The default is a check mark.

While selected is set, selected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name.

Events⁠

EventTypeDescription
clickMouseEventDispatched when the chip is clicked. It bubbles, is composed, and is cancelable.
changeEventDispatched after the chip's selected state changes: a click toggles it, or its filter chip set selects or deselects it. It does not fire when code sets selected. It bubbles.
removeEventDispatched when the remove button is clicked. The chip then removes itself unless the event is canceled. It bubbles and is cancelable.

Calling preventDefault() on click reverts the toggle and suppresses change. A listener that does not cancel remove must also update the list that renders the chips. Neither change nor remove is composed, and a soft-disabled chip ignores clicks.

Props⁠

PropTypeDescription
badgeConcealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disabledbooleandefault falseWhether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled.
flipIconInRtlbooleandefault falseFlips the icons supplied by the iconName and removeTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons.
iconNamestringA Material Symbols icon name. This is an alternative to using the iconSnippet snippet. If both are provided, the iconSnippet snippet will take precedence, and a warning will be logged. See Icons.
removablebooleandefault falseShows a remove button at the end of the chip. See Removing.
removeTrailingIconNamestringA Material Symbols icon name. This is an alternative to using the removeTrailingIconSnippet snippet. If both are provided, the removeTrailingIconSnippet snippet will take precedence, and a warning will be logged. See Icons.
selectedbooleandefault falseMarks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection.
sizeChipSizeTypeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configurationSets how tall the chip is. See Size.
softDisabledbooleandefault falseWhether or not the chip is "soft-disabled" (disabled but still focusable).A soft-disabled chip looks disabled and ignores clicks, but stays focusable. Use this when a chip needs increased visibility when disabled. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargetTouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationThe area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size.
valueunknownThe chip's value: a filter chip set reports it as its own value or among its values while the chip is selected. Set from code it can be any value, such as a number or an object; the value attribute sets it to a string.
variantChipVariantTypeChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configurationSets whether the chip is raised with a shadow or flat with an outline. See Variants.

While disabled or soft-disabled is set, the remove button ignores clicks too.

Snippets⁠

SnippetDescription
childrenThe chip's label content.
iconSnippetThe icon to display in the chip, intended for a CsIcon or similarly sized visual content such as an SVG.
selectedIconSnippetThe icon to display in place of the leading icon while the chip is selected, intended for a CsIcon or equivalent. The default is a check mark.
removeTrailingIconSnippetThe icon on the remove button, intended for a CsIcon or equivalent. The default is a cross. Shown only while removable is set.

While selected is set, selected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name.

Events⁠

PropTypeDescription
onClickMouseEventDispatched when the chip is clicked. It bubbles, is composed, and is cancelable.
onChangeEventDispatched after the chip's selected state changes: a click toggles it, or its filter chip set selects or deselects it. It does not fire when code sets selected. It bubbles.
onRemoveEventDispatched when the remove button is clicked. The chip then removes itself unless the event is canceled. It bubbles and is cancelable.

Calling preventDefault() on click reverts the toggle and suppresses change. A listener that does not cancel remove must also update the list that renders the chips. Neither change nor remove is composed, and a soft-disabled chip ignores clicks.

Each attribute value has its own tokens; a cell shows its token's value, and selecting the cell shows the token's fallback path, with each name and value ready to copy. For example, the elevated column's container-color row is --ct-filter-chip-elevated-container-color, which defaults to --ct-sys-color-surface.

Variant⁠

Nameelevated
container-color--ct-sys-color-surface --ct-filter-chip-elevated-container-color
container-elevation--ct-sys-elevation-level1 --ct-filter-chip-elevated-container-elevation
selected-container-color--ct-sys-color-secondary-container --ct-filter-chip-elevated-selected-container-color
hover-container-elevation--ct-sys-elevation-level2 --ct-filter-chip-elevated-hover-container-elevation
focus-container-elevation--ct-sys-elevation-level1 --ct-filter-chip-elevated-focus-container-elevation
pressed-container-elevation--ct-sys-elevation-level1 --ct-filter-chip-elevated-pressed-container-elevation
disabled-container-color--ct-sys-color-on-surface --ct-filter-chip-elevated-disabled-container-color
disabled-container-elevation--ct-sys-elevation-level0 --ct-filter-chip-elevated-disabled-container-elevation
disabled-container-opacity0.12 --ct-filter-chip-elevated-disabled-container-opacity

Other tokens⁠

These stay the same whatever the variant.

TokenValue
--ct-filter-chip-container-elevation--ct-sys-elevation-level0 --ct-filter-chip-container-elevation
--ct-filter-chip-container-height32px --ct-filter-chip-container-height
--ct-filter-chip-disabled-label-text-color--ct-sys-color-on-surface --ct-filter-chip-disabled-label-text-color
--ct-filter-chip-disabled-label-text-opacity0.38 --ct-filter-chip-disabled-label-text-opacity
--ct-filter-chip-disabled-leading-icon-color--ct-sys-color-on-surface --ct-filter-chip-disabled-leading-icon-color
--ct-filter-chip-disabled-leading-icon-opacity0.38 --ct-filter-chip-disabled-leading-icon-opacity
--ct-filter-chip-disabled-outline-color--ct-sys-color-on-surface --ct-filter-chip-disabled-outline-color
--ct-filter-chip-disabled-outline-opacity0.12 --ct-filter-chip-disabled-outline-opacity
--ct-filter-chip-disabled-selected-container-color--ct-sys-color-on-surface --ct-filter-chip-disabled-selected-container-color
--ct-filter-chip-disabled-selected-container-opacity0.12 --ct-filter-chip-disabled-selected-container-opacity
--ct-filter-chip-disabled-trailing-icon-color--ct-sys-color-on-surface --ct-filter-chip-disabled-trailing-icon-color
--ct-filter-chip-disabled-trailing-icon-opacity0.38 --ct-filter-chip-disabled-trailing-icon-opacity
--ct-filter-chip-focus-container-elevation--ct-sys-elevation-level0 --ct-filter-chip-focus-container-elevation
--ct-filter-chip-focus-label-text-color--ct-sys-color-on-surface-variant --ct-filter-chip-focus-label-text-color
--ct-filter-chip-focus-leading-icon-color--ct-sys-color-primary --ct-filter-chip-focus-leading-icon-color
--ct-filter-chip-focus-trailing-icon-color--ct-sys-color-on-surface-variant --ct-filter-chip-focus-trailing-icon-color
--ct-filter-chip-hover-container-elevation--ct-sys-elevation-level0 --ct-filter-chip-hover-container-elevation
--ct-filter-chip-hover-label-text-color--ct-sys-color-on-surface-variant --ct-filter-chip-hover-label-text-color
--ct-filter-chip-hover-leading-icon-color--ct-sys-color-primary --ct-filter-chip-hover-leading-icon-color
--ct-filter-chip-hover-state-layer-color--ct-sys-color-on-surface-variant --ct-filter-chip-hover-state-layer-color
--ct-filter-chip-hover-state-layer-opacity--ct-sys-state-hover-state-layer-opacity --ct-filter-chip-hover-state-layer-opacity
--ct-filter-chip-hover-trailing-icon-color--ct-sys-color-on-surface-variant --ct-filter-chip-hover-trailing-icon-color
--ct-filter-chip-icon-label-space8px --ct-filter-chip-icon-label-space
--ct-filter-chip-icon-size18px --ct-filter-chip-icon-size
--ct-filter-chip-label-text-color--ct-sys-color-on-surface-variant --ct-filter-chip-label-text-color
--ct-filter-chip-label-text-font--ct-sys-typescale-label-large-font --ct-filter-chip-label-text-font
--ct-filter-chip-label-text-line-height--ct-sys-typescale-label-large-line-height --ct-filter-chip-label-text-line-height
--ct-filter-chip-label-text-size--ct-sys-typescale-label-large-size --ct-filter-chip-label-text-size
--ct-filter-chip-label-text-weight--ct-sys-typescale-label-large-weight --ct-filter-chip-label-text-weight
--ct-filter-chip-leading-icon-color--ct-sys-color-primary --ct-filter-chip-leading-icon-color
--ct-filter-chip-leading-space16px --ct-filter-chip-leading-space
--ct-filter-chip-outline-color--ct-sys-color-outline --ct-filter-chip-outline-color
--ct-filter-chip-outline-width1px --ct-filter-chip-outline-width
--ct-filter-chip-pressed-container-elevation--ct-sys-elevation-level0 --ct-filter-chip-pressed-container-elevation
--ct-filter-chip-pressed-label-text-color--ct-sys-color-on-surface-variant --ct-filter-chip-pressed-label-text-color
--ct-filter-chip-pressed-leading-icon-color--ct-sys-color-primary --ct-filter-chip-pressed-leading-icon-color
--ct-filter-chip-pressed-state-layer-color--ct-sys-color-on-surface-variant --ct-filter-chip-pressed-state-layer-color
--ct-filter-chip-pressed-state-layer-opacity--ct-sys-state-pressed-state-layer-opacity --ct-filter-chip-pressed-state-layer-opacity
--ct-filter-chip-pressed-trailing-icon-color--ct-sys-color-on-surface-variant --ct-filter-chip-pressed-trailing-icon-color
--ct-filter-chip-selected-container-color--ct-sys-color-secondary-container --ct-filter-chip-selected-container-color
--ct-filter-chip-selected-focus-label-text-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-focus-label-text-color
--ct-filter-chip-selected-focus-leading-icon-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-focus-leading-icon-color
--ct-filter-chip-selected-focus-trailing-icon-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-focus-trailing-icon-color
--ct-filter-chip-selected-hover-label-text-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-hover-label-text-color
--ct-filter-chip-selected-hover-leading-icon-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-hover-leading-icon-color
--ct-filter-chip-selected-hover-state-layer-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-hover-state-layer-color
--ct-filter-chip-selected-hover-state-layer-opacity--ct-sys-state-hover-state-layer-opacity --ct-filter-chip-selected-hover-state-layer-opacity
--ct-filter-chip-selected-hover-trailing-icon-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-hover-trailing-icon-color
--ct-filter-chip-selected-label-text-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-label-text-color
--ct-filter-chip-selected-leading-icon-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-leading-icon-color
--ct-filter-chip-selected-outline-width0px --ct-filter-chip-selected-outline-width
--ct-filter-chip-selected-pressed-label-text-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-pressed-label-text-color
--ct-filter-chip-selected-pressed-leading-icon-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-pressed-leading-icon-color
--ct-filter-chip-selected-pressed-state-layer-color--ct-sys-color-on-surface-variant --ct-filter-chip-selected-pressed-state-layer-color
--ct-filter-chip-selected-pressed-state-layer-opacity--ct-sys-state-pressed-state-layer-opacity --ct-filter-chip-selected-pressed-state-layer-opacity
--ct-filter-chip-selected-pressed-trailing-icon-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-pressed-trailing-icon-color
--ct-filter-chip-selected-trailing-icon-color--ct-sys-color-on-secondary-container --ct-filter-chip-selected-trailing-icon-color
--ct-filter-chip-trailing-icon-color--ct-sys-color-on-surface-variant --ct-filter-chip-trailing-icon-color
--ct-filter-chip-trailing-space16px --ct-filter-chip-trailing-space
--ct-filter-chip-with-leading-icon-leading-space8px --ct-filter-chip-with-leading-icon-leading-space
--ct-filter-chip-with-trailing-icon-trailing-space8px --ct-filter-chip-with-trailing-icon-trailing-space

Names and states⁠

A filter chip is announced as a toggle button that is either pressed or not pressed. It follows the toggle form of the WAI-ARIA Authoring Practices: Button pattern.

  • The slotted label text is the accessible name. Give a chip with no text an aria-label, and keep any visible words in it.
  • Two ARIA attributes on the host reach the chip: aria-label, for the filter button, and aria-label-remove, for the remove button. Any other aria-* attribute on the host has no effect.
  • A screen reader announces the chip as pressed while selected is set and as not pressed otherwise.
  • A removable chip names its remove button from aria-label-remove. Without it, an aria-label becomes "Remove" followed by that label, and with neither the button reads "Remove" plus the chip's text.
  • The word "Remove" is English only, so set aria-label-remove on a page in another language.
  • The leading icon, including the check mark, is hidden from assistive technology, so nothing in it joins the name. An alt on a slotted image is hidden too.
  • tooltip-value is the filter button's description: a screen reader announces it after the name, unless it only repeats the name. The remove button carries no description.
  • A filter chip is a toggle and not a form control: it has no name or value, and it submits nothing. Use a checkbox for a choice that belongs to a form.
  • A filter chip set is announced as a group. It has no name of its own, so give each set an aria-label that names its filters, such as "Dietary needs". The set holds no selection; each chip states its own with aria-pressed.

Keyboard and focus⁠

Key Action
Tab Moves focus to the chip's filter button, or to the current chip of a filter chip set
Enter Toggles the filter, or removes the chip when the remove button has focus
Space Toggles the filter, or removes the chip when the remove button has focus
Right Arrow On a removable chip, moves focus from the filter button to the remove button
Left Arrow Moves focus from the remove button back to the filter button

Enter and Space are the native button's own behavior. The arrow keys are the chip's.

  • Focus shows a ring on keyboard focus only. A removable chip has two rings, one for the filter button and one for the remove button.
  • disabled removes the chip from the Tab order and announces it as unavailable. soft-disabled keeps it in the Tab order, announces it as dimmed, and blocks the toggle.
  • Tab does not reach the remove button: reach it with the arrow keys.
  • In a filter chip set, one chip is the Tab stop. The arrow keys move focus between chips, skipping disabled ones and wrapping at the ends; soft-disabled chips are not skipped. Home and End move to the first and last chip, End landing on a removable last chip's remove button, and focus stays where it was when that chip is disabled. Moving back onto a removable chip lands on its remove button. Up and Down Arrow are not handled, and a tabindex on a chip in a set has no effect.
  • A chip with hidden is left out of the set's keyboard travel: the arrow keys, Home, and End pass over it, and it is never the Tab stop.
  • Outside a set, each chip is reached with Tab and has no arrow-key movement between chips.

Pointer and touch⁠

  • touch-target offers none, overflow and wrapper. WCAG 2.5.8 asks for 24 by 24 pixels, and the default reaches at least 48 by 48.
  • A small chip paints 32 pixels tall, and an extra-small chip is still taller than 24, so even none clears the WCAG minimum. The remove button takes its own touch target.
  • The Size examples show each setting.

Display settings⁠

  • In forced-colors mode, a selected chip's label and icon take ActiveText, and a disabled chip's label and leading icon take GrayText at full opacity.
  • Reduced motion: under a reduced-motion preference, the focus ring's animation stops.
  • On a right-to-left page the arrow keys swap direction, and flip-icon-in-rtl mirrors an icon from icon-name. Slotted icons are not mirrored.

Standards⁠

With its defaults, the filter chip meets seven WCAG 2.2 success criteria:

  • 2.1.1 Keyboard (A)
  • 2.1.2 No Keyboard Trap (A)
  • 2.5.2 Pointer Cancellation (A)
  • 2.4.7 Focus Visible (AA)
  • 2.5.8 Target Size (Minimum) (AA)
  • 1.3.1 Info and Relationships (A)
  • 1.4.13 Content on Hover or Focus (AA)

Four more depend on how you use it:

  • 4.1.2 Name, Role, Value (A): write a visible label, or an aria-label when the chip has none, and give each set an aria-label.
  • 2.5.3 Label in Name (A): keep the visible label's words in any aria-label.
  • 2.4.6 Headings and Labels (AA): write a label that says which filter the chip switches.
  • 1.1.1 Non-text Content (A): carry an icon's meaning in the label, because the leading icon is hidden from assistive technology.