packages/mdc-chips/chip-set/README.md
Chip sets represent logical groups of chips.
Note: there's work planned to replace the mdc-evolution-* prefix of chips with the standard mdc-chip-* prefix.
Chip sets have two varieties: layout grid chip sets and listbox chip sets.
Note: chip sets use the roving tabindex pattern for keyboard navigation. As a result, only one chip action should be in the tab sequence with tabindex="0". All other chip actions, even other action(s) in the same chip, should have tabindex="-1".
Layout grid chip sets follow the layout grid interaction pattern. They contain either action chips or input chips.
<span class="mdc-evolution-chip-set" role="grid">
<span class="mdc-evolution-chip-set__chips" role="presentation">
<!-- Contains either action chips or input chips -->
</span>
</span>
Listbox chip sets follow the follow the listbox interaction pattern They contain filter chips chips.
<span class="mdc-evolution-chip-set" role="listbox" aria-orientation="horizontal" aria-multiselectable="true">
<span class="mdc-evolution-chip-set__chips" role="presentation">
<!-- Contains filter chips -->
</span>
</span>
Listbox chip sets support both multi-selection and single-selection. The aria-multiselectable attribute dictates which behavior is applied.
<span class="mdc-evolution-chip-set" role="listbox" aria-orientation="horizontal" aria-multiselectable="false">
<span class="mdc-evolution-chip-set__chips" role="presentation">
<!-- Contains filter chips -->
</span>
</span>
| CSS Class | Description |
|---|---|
mdc-evolution-chip-set | Mandatory, for the chip set root. |
mdc-evolution-chip-set__chips | Mandatory, for the element containing the chips. |
mdc-evolution-chip-set--overflow | Optional, causes the chips to overflow instead of wrap (their default behavior). |
Access to theme mixins require importing the chips theme style module.
@use "@material/chips";
| Mixin | Description |
|---|---|
horizontal-space-between-chips($space) | Sets the horizontal space between chips in the chip set. |
vertical-space-between-chips($space) | Sets the vertical space between chips in the chip set. |
MDCChipSet methods| Method Signature | Description |
|---|---|
getChipIndexByID(chipID: string): number | Returns the index of the chip with the given id. |
getChipIdAtIndex(index: number): string | Returns the id of the chip at the given index. |
getSelectedChipIndexes(): ReadonlySet<number> | Returns the indexes of the selcted chips (if any). Only supported for listbox chip sets. |
setChipSelected(index: number, action: MDCChipActionType, isSelected: boolean): void | Sets the chip to be selected at the given index. Only supported for listbox chip sets. |
isChipSelected(index: number, action: MDCChipActionType): boolean | Returns the selected state of the chip at the given index. Only supported for listbox chip sets. |
removeChip(index: number): boolean | Returns the selected state of the chip at the given index. Only supported for listbox chip sets. |
MDCChipSetEvents| Event name | Detail | Description |
|---|---|---|
MDCChipSet:interaction | MDCChipSetInteractionEventDetail | Emitted when a chip is interacted with. |
MDCChipSet:removal | MDCChipSetRemovalEventDetail | Emitted when a chip is removed. Check the detail to know when the removal animation is complete. |
MDCChipSet:selection | MDCChipSetSelectionEventDetail | Emitted when a chip selected state changes. |
MDCChipSetAdapter| Method Signature | Description |
|---|---|
announceMessage(message: string): void | Announces the message to screen readers via an aria-live region. |
emitEvent<D extends object>(eventName: MDCChipSetEvents, eventDetail: D): void | Emits the given eventName with the given eventDetail. |
getAttribute(attrName: MDCChipSetAttributes): string|null | Returns the value for the given if attribute or null if it does not exist. |
getChipActionsAtIndex(index: number): MDCChipActionType[] | Returns the actions provided by the child chip at the given index. |
getChipCount(): number | Returns the number of child chips. |
getChipIdAtIndex(index: number): string | Returns the ID of the chip at the given index. |
getChipIndexById(chipID: string): number | Returns the index of the child chip with the matching ID. |
isChipFocusableAtIndex(index: number, actionType: MDCChipActionType): boolean | Proxies to the MDCChip#isActionFocusable method. |
isChipSelectableAtIndex(index: number, actionType: MDCChipActionType): boolean | Proxies to the MDCChip#isActionSelectable method. |
isChipSelectedAtIndex(index: number, actionType: MDCChipActionType): boolean | Proxies to the MDCChip#isActionSelected method. |
removeChipAtIndex(index: number): void | Removes the chip at the given index. |
setChipFocusAtIndex(index: number, action: MDCChipActionType, focus: FocusBehavior): void | Proxies to the MDCChip#setActionFocus method. |
setChipSelectedAtIndex(index: number, actionType: MDCChipActionType, isSelected: boolean): void | Proxies to the MDCChip#setActionSelected method. |
startChipAnimationAtIndex(index: number, animation: Animation): void | Starts the chip animation at the given index. |
MDCChipSetFoundation| Method Signature | Description |
|---|---|
handleChipAnimation(event: ChipAnimationEvent): void | Handles the chip animation event. |
handleChipInteraction(event: ChipInteractionEvent): void | Handles the chip interaction event. |
handleChipNavigation(event: ChipNavigationEvent): void | Handles the chip navigation event. |
getSelectedChipIndexes(): ReadonlySet<number> | Returns the unique selected indexes of the chips (if any). |
setChipSelected(index: number, action: MDCChipActionType, isSelected: boolean): void | Sets the selected state of the chip at the given index and action. |
isChipSelected(index: number, action: MDCChipActionType): boolean | Returns the selected state of the chip at the given index and action. |
removeChip(index: number): void | Removes the chip at the given index. |
addChip(index: number): void | Animates the addition of the chip at the given index. |
If you are using a JavaScript framework, such as React or Angular, you can create a chip set for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.