1 |
|
2 | title: "Chip set"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "Chip sets represent logical groups of chips."
|
6 | iconId: chip
|
7 | path: /catalog/chips/chipset/
|
8 | -->
|
9 |
|
10 | # Chip set
|
11 |
|
12 | Chip sets represent logical groups of [chips](../chip).
|
13 |
|
14 | ## Basic usage
|
15 |
|
16 | **Note**: there's work planned to replace the `mdc-evolution-*` prefix of chips with the standard `mdc-chip-*` prefix.
|
17 |
|
18 | ### HTML structure
|
19 |
|
20 | Chip sets have two varieties: layout grid chip sets and listbox chip sets.
|
21 |
|
22 | Note: chip sets use the [roving `tabindex` pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_roving_tabindex) for keyboard navigation. As a result, only one [chip action](../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"`.
|
23 |
|
24 | #### Layout grid chip sets
|
25 |
|
26 | Layout grid chip sets follow the [layout grid](https://www.w3.org/TR/wai-aria-practices/#layoutGrid) interaction pattern. They contain either [action chips](../chip#action-chips) or [input chips](../chip#input-chips).
|
27 |
|
28 | ```html
|
29 | <span class="mdc-evolution-chip-set" role="grid">
|
30 | <span class="mdc-evolution-chip-set__chips" role="presentation">
|
31 | <!-- Contains either action chips or input chips -->
|
32 | </span>
|
33 | </span>
|
34 | ```
|
35 |
|
36 | #### Listbox chip sets
|
37 |
|
38 | Listbox chip sets follow the follow the [listbox](https://www.w3.org/TR/wai-aria-practices/#Listbox) interaction pattern They contain [filter chips chips](../chip#filter-chips).
|
39 |
|
40 | ```html
|
41 | <span class="mdc-evolution-chip-set" role="listbox" aria-orientation="horizontal" aria-multiselectable="true">
|
42 | <span class="mdc-evolution-chip-set__chips" role="presentation">
|
43 | <!-- Contains filter chips -->
|
44 | </span>
|
45 | </span>
|
46 | ```
|
47 |
|
48 | Listbox chip sets support both multi-selection and single-selection. The [`aria-multiselectable` attribute](https://www.w3.org/TR/wai-aria-1.1/#aria-multiselectable) dictates which behavior is applied.
|
49 |
|
50 | ```html
|
51 | <span class="mdc-evolution-chip-set" role="listbox" aria-orientation="horizontal" aria-multiselectable="false">
|
52 | <span class="mdc-evolution-chip-set__chips" role="presentation">
|
53 | <!-- Contains filter chips -->
|
54 | </span>
|
55 | </span>
|
56 | ```
|
57 |
|
58 | ## API
|
59 |
|
60 | ### CSS classes
|
61 |
|
62 | CSS Class | Description
|
63 | --- | ---
|
64 | `mdc-evolution-chip-set` | Mandatory, for the chip set root.
|
65 | `mdc-evolution-chip-set__chips` | Mandatory, for the element containing the chips.
|
66 | `mdc-evolution-chip-set--overflow` | Optional, causes the chips to overflow instead of wrap (their default behavior).
|
67 |
|
68 | ### Sass mixins
|
69 |
|
70 | Access to theme mixins require importing the chips theme style module.
|
71 |
|
72 | ```scss
|
73 | @use "@material/chips";
|
74 | ```
|
75 |
|
76 | Mixin | Description
|
77 | --- | ---
|
78 | `horizontal-space-between-chips($space)` | Sets the horizontal space between chips in the chip set.
|
79 | `vertical-space-between-chips($space)` | Sets the vertical space between chips in the chip set.
|
80 |
|
81 | ### `MDCChipSet` methods
|
82 |
|
83 | Method Signature | Description
|
84 | --- | ---
|
85 | `getChipIndexByID(chipID: string): number` | Returns the index of the chip with the given `id`.
|
86 | `getChipIdAtIndex(index: number): string` | Returns the `id` of the chip at the given index.
|
87 | `getSelectedChipIndexes(): ReadonlySet<number>` | Returns the indexes of the selcted chips (if any). Only supported for [listbox chip sets](#listbox-chip-sets).
|
88 | `setChipSelected(index: number, action: MDCChipActionType, isSelected: boolean): void` | Sets the chip to be selected at the given index. Only supported for [listbox chip sets](#listbox-chip-sets).
|
89 | `isChipSelected(index: number, action: MDCChipActionType): boolean` | Returns the selected state of the chip at the given index. Only supported for [listbox chip sets](#listbox-chip-sets).
|
90 | `removeChip(index: number): boolean` | Returns the selected state of the chip at the given index. Only supported for [listbox chip sets](#listbox-chip-sets).
|
91 |
|
92 | ### `MDCChipSetEvents`
|
93 |
|
94 | Event name | Detail | Description
|
95 | --- | --- | ---
|
96 | `MDCChipSet:interaction` | `MDCChipSetInteractionEventDetail` | Emitted when a chip is interacted with.
|
97 | `MDCChipSet:removal` | `MDCChipSetRemovalEventDetail` | Emitted when a chip is removed. Check the detail to know when the removal animation is complete.
|
98 | `MDCChipSet:selection` | `MDCChipSetSelectionEventDetail` | Emitted when a chip selected state changes.
|
99 |
|
100 | ### `MDCChipSetAdapter`
|
101 |
|
102 | Method Signature | Description
|
103 | --- | ---
|
104 | `announceMessage(message: string): void` | Announces the message to screen readers via an [`aria-live` region](https://www.w3.org/TR/wai-aria-1.1/#aria-live).
|
105 | `emitEvent<D extends object>(eventName: MDCChipSetEvents, eventDetail: D): void` | Emits the given `eventName` with the given `eventDetail`.
|
106 | `getAttribute(attrName: MDCChipSetAttributes): string\|null` | Returns the value for the given if attribute or `null` if it does not exist.
|
107 | `getChipActionsAtIndex(index: number): MDCChipActionType[]` | Returns the actions provided by the child chip at the given index.
|
108 | `getChipCount(): number` | Returns the number of child chips.
|
109 | `getChipIdAtIndex(index: number): string` | Returns the ID of the chip at the given index.
|
110 | `getChipIndexById(chipID: string): number` | Returns the index of the child chip with the matching ID.
|
111 | `isChipFocusableAtIndex(index: number, actionType: MDCChipActionType): boolean` | Proxies to the `MDCChip#isActionFocusable` method.
|
112 | `isChipSelectableAtIndex(index: number, actionType: MDCChipActionType): boolean` | Proxies to the `MDCChip#isActionSelectable` method.
|
113 | `isChipSelectedAtIndex(index: number, actionType: MDCChipActionType): boolean` | Proxies to the `MDCChip#isActionSelected` method.
|
114 | `removeChipAtIndex(index: number): void` | Removes the chip at the given index.
|
115 | `setChipFocusAtIndex(index: number, action: MDCChipActionType, focus: FocusBehavior): void` | Proxies to the `MDCChip#setActionFocus` method.
|
116 | `setChipSelectedAtIndex(index: number, actionType: MDCChipActionType, isSelected: boolean): void` | Proxies to the `MDCChip#setActionSelected` method.
|
117 | `startChipAnimationAtIndex(index: number, animation: Animation): void` | Starts the chip animation at the given index.
|
118 |
|
119 | ### `MDCChipSetFoundation`
|
120 |
|
121 | Method Signature | Description
|
122 | --- | ---
|
123 | `handleChipAnimation(event: ChipAnimationEvent): void` | Handles the chip animation event.
|
124 | `handleChipInteraction(event: ChipInteractionEvent): void` | Handles the chip interaction event.
|
125 | `handleChipNavigation(event: ChipNavigationEvent): void` | Handles the chip navigation event.
|
126 | `getSelectedChipIndexes(): ReadonlySet<number>` | Returns the unique selected indexes of the chips (if any).
|
127 | `setChipSelected(index: number, action: MDCChipActionType, isSelected: boolean): void` | Sets the selected state of the chip at the given index and action.
|
128 | `isChipSelected(index: number, action: MDCChipActionType): boolean` | Returns the selected state of the chip at the given index and action.
|
129 | `removeChip(index: number): void` | Removes the chip at the given index.
|
130 | `addChip(index: number): void` | Animates the addition of the chip at the given index.
|
131 |
|
132 | ### Usage within frameworks
|
133 |
|
134 | 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](../../../docs/integrating-into-frameworks.md).
|