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.
Reference docs
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
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
is set, and theselectedselected-iconslot swaps in your own. - A trailing remove button, switched on by
, takes the chip off the page when it is clicked.removable andbadge-value add a count or a dot, with no separate badge element to place.badge-dot adds a tooltip that a screen reader also reads as the chip's description.tooltip-value reaches at least 48 by 48 pixels, even though a small chip paints 32 pixels tall.touch-target- 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-labelthat 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
variantoutlinedelevatedoutlined
Size
sizesmallextra-smallsmall
touch-targetoverflowwrappernone
Icons
Give a chip a leading icon by name with icon-namecw-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-nameremove-trailing-icon slot replace the built-in cross on a removable chip. flip-icon-in-rtlicon-name
Badges
badge-valuebadge-dotbadge-valuebadge-concealed
Tooltips
tooltip-valuetooltip-positionend-center
Selection
A click toggles selectedselectedchange, which fires after a click and never when code sets selectedchange to drive the list the chip filters.
Removing
removableremove, 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
disabledsoft-disabled
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.
Properties
| Property | Attribute | Type | Description |
|---|---|---|---|
compareWith | (a: TItem, b: TItem) => boolean | Decides whether two values name the same chip. When set, neither valueKey nor the default matching applies. | |
selectionMode | selection-mode | SelectionModedefault SelectionMode.Multi | How 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. |
value | value | TItem | The 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. |
valueKey | value-key | string | The field that identifies an object value: two objects match when this field holds the same value on both. |
values | 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. |
Slots
| Slot | Description |
|---|---|
| (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
| Event | Type | Detail | Description |
|---|---|---|---|
change | SelectionChangeEvent | SelectionChangeEventDetail<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
| Prop | Type | Description |
|---|---|---|
compareWith | (a: TItem, b: TItem) => boolean | Decides whether two values name the same chip. When set, neither valueKey nor the default matching applies. |
selectionMode | SelectionModeTypedefault SelectionMode.Multi | How 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. |
value | TItem | The 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. |
valueKey | string | The field that identifies an object value: two objects match when this field holds the same value on both. |
values | 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. |
Children
| Child | Description |
|---|---|
children | The 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
| Prop | Argument | Description |
|---|---|---|
onChange | SelectionChangeEvent<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
| Parameter | Type | Description |
|---|---|---|
SelectionMode | SelectionMode?default SelectionMode.Multi | How 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. |
Value | TItem | The 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. |
ValueExpression | Expression<Func<TItem>>? | Gets or sets an expression that identifies the bound value. |
Values | IList<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. |
ValuesExpression | Expression<Func<IList<TItem>>>? | Gets or sets an expression that identifies the bound value. |
Render fragments
| Parameter | Type | Description |
|---|---|---|
ChildContent | RenderFragment? | 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
| Parameter | Type | Description |
|---|---|---|
OnChange | EventCallback<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
| Input | Type | Description |
|---|---|---|
compareWith | (a: TItem, b: TItem) => boolean | Decides whether two values name the same chip. When set, neither valueKey nor the default matching applies. |
selectionMode | SelectionModeTypedefault SelectionMode.Multi | How 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. |
value | TItem | The 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. |
valueKey | string | The field that identifies an object value: two objects match when this field holds the same value on both. |
values | 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. |
Content projection
| Content | Description |
|---|---|
content with no slot | The 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
| Output | Event | Description |
|---|---|---|
cwChange | SelectionChangeEvent | 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. |
Props
| Prop | Type | Description |
|---|---|---|
compareWith | (a: TItem, b: TItem) => boolean | Decides whether two values name the same chip. When set, neither valueKey nor the default matching applies. |
selectionMode | SelectionModeTypedefault SelectionMode.Multi | How 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. |
value | TItem | The 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. |
valueKey | string | The field that identifies an object value: two objects match when this field holds the same value on both. |
values | 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. |
Slots
| Slot | Description |
|---|---|
default | The 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
| Event | Type | Description |
|---|---|---|
change | SelectionChangeEvent | 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. |
Props
| Prop | Type | Description |
|---|---|---|
compareWith | (a: TItem, b: TItem) => boolean | Decides whether two values name the same chip. When set, neither valueKey nor the default matching applies. |
selectionMode | SelectionModeTypedefault SelectionMode.Multi | How 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. |
value | TItem | The 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. |
valueKey | string | The field that identifies an object value: two objects match when this field holds the same value on both. |
values | 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. |
Snippets
| Snippet | Description |
|---|---|
children | The 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
| Prop | Type | Description |
|---|---|---|
onChange | SelectionChangeEvent | 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. |
Properties
| Property | Attribute | Type | Description |
|---|---|---|---|
badgeConcealed | badge-concealed | booleandefault false | Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges. |
badgeDot | badge-dot | booleandefault false | Shows the badge as a small dot with no text, whether or not badgeValue is set. See Badges. |
badgeValue | badge-value | string | The badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges. |
disabled | disabled | booleandefault false | Whether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled. |
flipIconInRtl | flip-icon-in-rtl | booleandefault false | Flips the icons supplied by the icon-name and remove-trailing-icon-name properties in RTL mode. A slotted icon is not flipped. See Icons. |
iconName | icon-name | string | A 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. |
removable | removable | booleandefault false | Shows a remove button at the end of the chip. See Removing. |
removeTrailingIconName | remove-trailing-icon-name | string | A 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. |
selected | selected | booleandefault false | Marks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection. |
size | sizesmall, extra-small | ChipSizeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configuration | Sets how tall the chip is. See Size. |
softDisabled | soft-disabled | booleandefault false | Whether 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. |
tooltipPosition | tooltip-positionstart-start, start-center, start-end, center-start, center-end, end-start, end-center, end-end | TooltipPositionTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configuration | Where the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips. |
tooltipValue | tooltip-value | string | 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. |
touchTarget | touch-targetnone, overflow, wrapper | TouchTargetTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The 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. |
value | value | unknown | The 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. |
variant | variantelevated, outlined | ChipVariantChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configuration | Sets whether the chip is raised with a shadow or flat with an outline. See Variants. |
While disabledsoft-disabled
Slots
| Slot | Description |
|---|---|
| (default) | The chip's label content. |
icon | The icon to display in the chip, intended for a cw-icon or similarly sized visual content such as an SVG. |
selected-icon | The 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-icon | The icon on the remove button, intended for a cw-icon or equivalent. The default is a cross. Shown only while removable is set. |
While selectedselected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name
Events
| Event | Type | Detail | Description |
|---|---|---|---|
click | MouseEvent | — | Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable. |
change | Event | — | 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. |
remove | Event | — | 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
| Prop | Type | Description |
|---|---|---|
badgeConcealed | booleandefault false | Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges. |
badgeDot | booleandefault false | Shows the badge as a small dot with no text, whether or not badgeValue is set. See Badges. |
badgeValue | string | The badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges. |
disabled | booleandefault false | Whether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled. |
flipIconInRtl | booleandefault false | Flips the icons supplied by the iconName and removeTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons. |
iconName | string | A 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. |
removable | booleandefault false | Shows a remove button at the end of the chip. See Removing. |
removeTrailingIconName | string | A 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. |
selected | booleandefault false | Marks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection. |
size | ChipSizeTypeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configuration | Sets how tall the chip is. See Size. |
softDisabled | booleandefault false | Whether 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. |
tooltipPosition | TooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configuration | Where the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips. |
tooltipValue | string | 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. |
touchTarget | TouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The 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. |
value | unknown | The 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. |
variant | ChipVariantTypeChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configuration | Sets whether the chip is raised with a shadow or flat with an outline. See Variants. |
While disabledsoft-disabled
Children
| Child | Description |
|---|---|
children | The 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 selectedselected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name
Events
| Prop | Argument | Description |
|---|---|---|
onClick | React.MouseEvent<HTMLElement> | Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable. |
onChange | React.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. |
onRemove | Event | 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
BadgeConcealed | bool?default false | Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges. |
BadgeDot | bool?default false | Shows the badge as a small dot with no text, whether or not BadgeValue is set. See Badges. |
BadgeValue | string? | The badge's text. While it is empty and BadgeDot is not set, no badge renders. Ignored if BadgeDot is set. See Badges. |
Disabled | bool?default false | Whether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled. |
FlipIconInRtl | bool?default false | Flips the icons supplied by the IconName and RemoveTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons. |
IconName | string? | 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. |
Removable | bool?default false | Shows a remove button at the end of the chip. See Removing. |
RemoveTrailingIconName | string? | 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. |
Selected | booldefault false | Marks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection. |
SelectedExpression | Expression<Func<bool>>? | Gets or sets an expression that identifies the bound value. |
Size | ChipSize?ChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configuration | Sets how tall the chip is. See Size. |
SoftDisabled | bool?default false | Whether 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. |
TooltipPosition | TooltipPosition?TooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configuration | Where the tooltip appears around the element, such as above or beside it. It has no effect without TooltipValue. See Tooltips. |
TooltipValue | string? | 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. |
TouchTarget | TouchTarget?TouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The 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. |
Value | TItem | The 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. |
Variant | ChipVariant?ChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configuration | Sets whether the chip is raised with a shadow or flat with an outline. See Variants. |
While disabledsoft-disabled
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>
| Parameter | Type | Description |
|---|---|---|
ChildContent | RenderFragment? | The chip's label content. |
Icon | RenderFragment? | The icon to display in the chip, intended for a CbIcon or similarly sized visual content such as an SVG. |
RemoveTrailingIcon | RenderFragment? | The icon on the remove button, intended for a CbIcon or equivalent. The default is a cross. Shown only while Removable is set. |
SelectedIcon | RenderFragment? | 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 selectedselected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name
Event callbacks
| Parameter | Type | Description |
|---|---|---|
OnClick | EventCallback<MouseEventArgs> | Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable. |
OnChange | EventCallback<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. |
OnRemove | EventCallback | 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.
Inputs
| Input | Type | Description |
|---|---|---|
badgeConcealed | booleandefault false | Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges. |
badgeDot | booleandefault false | Shows the badge as a small dot with no text, whether or not badgeValue is set. See Badges. |
badgeValue | string | The badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges. |
disabled | booleandefault false | Whether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled. |
flipIconInRtl | booleandefault false | Flips the icons supplied by the iconName and removeTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons. |
iconName | string | A 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. |
removable | booleandefault false | Shows a remove button at the end of the chip. See Removing. |
removeTrailingIconName | string | A 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. |
selected | booleandefault false | Marks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection. |
size | ChipSizeTypeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configuration | Sets how tall the chip is. See Size. |
softDisabled | booleandefault false | Whether 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. |
tooltipPosition | TooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configuration | Where the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips. |
tooltipValue | string | 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. |
touchTarget | TouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The 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. |
value | unknown | The 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. |
variant | ChipVariantTypeChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configuration | Sets whether the chip is raised with a shadow or flat with an outline. See Variants. |
While disabledsoft-disabled
Content projection
| Content | Description |
|---|---|
content with no slot | The 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 selectedselected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name
Outputs
| Output | Event | Description |
|---|---|---|
cwClick | MouseEvent | Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable. |
cwChange | Event | 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. |
cwRemove | Event | 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
| Prop | Type | Description |
|---|---|---|
badgeConcealed | booleandefault false | Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges. |
badgeDot | booleandefault false | Shows the badge as a small dot with no text, whether or not badgeValue is set. See Badges. |
badgeValue | string | The badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges. |
disabled | booleandefault false | Whether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled. |
flipIconInRtl | booleandefault false | Flips the icons supplied by the iconName and removeTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons. |
iconName | string | A 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. |
removable | booleandefault false | Shows a remove button at the end of the chip. See Removing. |
removeTrailingIconName | string | A 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. |
selected | booleandefault false | Marks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection. |
size | ChipSizeTypeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configuration | Sets how tall the chip is. See Size. |
softDisabled | booleandefault false | Whether 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. |
tooltipPosition | TooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configuration | Where the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips. |
tooltipValue | string | 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. |
touchTarget | TouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The 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. |
value | unknown | The 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. |
variant | ChipVariantTypeChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configuration | Sets whether the chip is raised with a shadow or flat with an outline. See Variants. |
While disabledsoft-disabled
Slots
| Slot | Description |
|---|---|
default | The chip's label content. |
icon | The icon to display in the chip, intended for a CvIcon or similarly sized visual content such as an SVG. |
remove-trailing-icon | The icon on the remove button, intended for a CvIcon or equivalent. The default is a cross. Shown only while removable is set. |
selected-icon | The 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 selectedselected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name
Events
| Event | Type | Description |
|---|---|---|
click | MouseEvent | Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable. |
change | Event | 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. |
remove | Event | 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
| Prop | Type | Description |
|---|---|---|
badgeConcealed | booleandefault false | Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges. |
badgeDot | booleandefault false | Shows the badge as a small dot with no text, whether or not badgeValue is set. See Badges. |
badgeValue | string | The badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges. |
disabled | booleandefault false | Whether or not the chip is disabled.A disabled chip leaves the Tab order and ignores clicks. See Disabled and soft-disabled. |
flipIconInRtl | booleandefault false | Flips the icons supplied by the iconName and removeTrailingIconName properties in RTL mode. A slotted icon is not flipped. See Icons. |
iconName | string | A 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. |
removable | booleandefault false | Shows a remove button at the end of the chip. See Removing. |
removeTrailingIconName | string | A 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. |
selected | booleandefault false | Marks the chip as selected: it shows its selected icon and style. A click on the chip toggles it. See Selection. |
size | ChipSizeTypeChipSize.Small, .ExtraSmalldefault ChipSize.Small, from the style configuration | Sets how tall the chip is. See Size. |
softDisabled | booleandefault false | Whether 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. |
tooltipPosition | TooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configuration | Where the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips. |
tooltipValue | string | 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. |
touchTarget | TouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The 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. |
value | unknown | The 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. |
variant | ChipVariantTypeChipVariant.Elevated, .Outlineddefault ChipVariant.Outlined, from the style configuration | Sets whether the chip is raised with a shadow or flat with an outline. See Variants. |
While disabledsoft-disabled
Snippets
| Snippet | Description |
|---|---|
children | The chip's label content. |
iconSnippet | The icon to display in the chip, intended for a CsIcon or similarly sized visual content such as an SVG. |
selectedIconSnippet | The 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. |
removeTrailingIconSnippet | The icon on the remove button, intended for a CsIcon or equivalent. The default is a cross. Shown only while removable is set. |
While selectedselected-icon content, or a built-in check mark when the slot is empty, replaces the leading icon, including one from icon-name
Events
| Prop | Type | Description |
|---|---|---|
onClick | MouseEvent | Dispatched when the chip is clicked. It bubbles, is composed, and is cancelable. |
onChange | Event | 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. |
onRemove | Event | 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.
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
| Name | elevated |
|---|---|
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-opacity | 0.12 --ct-filter-chip-elevated-disabled-container-opacity |
Other tokens
These stay the same whatever the variant.
| Token | Value |
|---|---|
--ct-filter-chip-container-elevation | --ct-sys-elevation-level0 --ct-filter-chip-container-elevation |
--ct-filter-chip-container-height | 32px --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-opacity | 0.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-opacity | 0.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-opacity | 0.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-opacity | 0.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-opacity | 0.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-space | 8px --ct-filter-chip-icon-label-space |
--ct-filter-chip-icon-size | 18px --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-space | 16px --ct-filter-chip-leading-space |
--ct-filter-chip-outline-color | --ct-sys-color-outline --ct-filter-chip-outline-color |
--ct-filter-chip-outline-width | 1px --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-width | 0px --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-space | 16px --ct-filter-chip-trailing-space |
--ct-filter-chip-with-leading-icon-leading-space | 8px --ct-filter-chip-with-leading-icon-leading-space |
--ct-filter-chip-with-trailing-icon-trailing-space | 8px --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, andaria-label-remove, for the remove button. Any otheraria-*attribute on the host has no effect. - A screen reader announces the chip as pressed while
is set and as not pressed otherwise.selected - A removable chip names its remove button from
aria-label-remove. Without it, anaria-labelbecomes "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-removeon 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
alton a slotted image is hidden too. 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.tooltip-value- 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-labelthat names its filters, such as "Dietary needs". The set holds no selection; each chip states its own witharia-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.
removes the chip from the Tab order and announces it as unavailable.disabled keeps it in the Tab order, announces it as dimmed, and blocks the toggle.soft-disabled- 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
tabindexon a chip in a set has no effect. - A chip with
hiddenis 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
offerstouch-target ,none andoverflow . WCAG 2.5.8 asks for 24 by 24 pixels, and the default reaches at least 48 by 48.wrapper- A small chip paints 32 pixels tall, and an extra-small chip is still taller than 24, so even
clears the WCAG minimum. The remove button takes its own touch target.none - 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 takeGrayTextat 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
mirrors an icon fromflip-icon-in-rtl . Slotted icons are not mirrored.icon-name
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-labelwhen the chip has none, and give each set anaria-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.