1 |
|
2 | title: "Chip action"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "Chip actions represent interactions regions of a chip."
|
6 | iconId: chip
|
7 | path: /catalog/chips/action/
|
8 | -->
|
9 |
|
10 | # Action
|
11 |
|
12 | Actions represent discrete interactive regions of a [chip](../chip). They are only ever used inside of chips.
|
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 | Actions have two varieties: primary and trailing. All chips must have a primary action. Chips may have an optional trailing action.
|
21 |
|
22 | #### Primary action
|
23 |
|
24 | Primary actions often use a `<button>` as the root.
|
25 |
|
26 | ```html
|
27 | <button class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" type="button" tabindex="0">
|
28 | <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
|
29 | <span class="mdc-evolution-chip__text-label">Chip label</span>
|
30 | </button>
|
31 | ```
|
32 |
|
33 | Primary actions may also be deletable.
|
34 |
|
35 | ```html
|
36 | <button class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" type="button" tabindex="0" data-mdc-deletable="true">
|
37 | <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
|
38 | <span class="mdc-evolution-chip__text-label">Chip label</span>
|
39 | </button>
|
40 | ```
|
41 |
|
42 | Primary actions may also be links.
|
43 |
|
44 | ```html
|
45 | <a class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" href="https://google.com" tabindex="0">
|
46 | <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
|
47 | <span class="mdc-evolution-chip__text-label">Chip label</span>
|
48 | </a>
|
49 | ```
|
50 |
|
51 | Primary actions accept an optional leading graphic.
|
52 |
|
53 | ```html
|
54 | <button class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" type="button" tabindex="0">
|
55 | <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
|
56 | <span class="mdc-evolution-chip__graphic">
|
57 | <span class="mdc-evolution-chip__icon mdc-evolution-chip__icon--primary material-icons">favorite</span>
|
58 | </span>
|
59 | <span class="mdc-evolution-chip__text-label">Chip label</span>
|
60 | </button>
|
61 | ```
|
62 |
|
63 | Primary actions can also be selectable, implementing the [`option` role](https://www.w3.org/TR/wai-aria-1.1/#option). Selectable primary actions require the graphic element with the included checkmark and may also include a leading graphic.
|
64 |
|
65 | ```html
|
66 | <span class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" role="option" aria-selected="false" tabindex="0">
|
67 | <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
|
68 | <span class="mdc-evolution-chip__graphic">
|
69 | <span class="mdc-evolution-chip__icon mdc-evolution-chip__icon--primary material-icons">favorite</span> <!-- optional -->
|
70 | <span class="mdc-evolution-chip__checkmark">
|
71 | <svg class="mdc-evolution-chip__checkmark-svg" viewBox="-2 -3 30 30">
|
72 | <path class="mdc-evolution-chip__checkmark-path"
|
73 | fill="none" stroke="black" d="M1.73,12.91 8.1,19.28 22.79,4.59" />
|
74 | </svg>
|
75 | </span>
|
76 | </span>
|
77 | <span class="mdc-evolution-chip__text-label">Chip label</span>
|
78 | </span>
|
79 | ```
|
80 |
|
81 | #### Trailing action
|
82 |
|
83 | Trailing actions always use a `<button> ` as the root.
|
84 |
|
85 | ```html
|
86 | <button class="mdc-evolution-chip__action mdc-evolution-chip__action--trailing" type="button" tabindex="-1" data-mdc-deletable="true">
|
87 | <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--trailing"></span>
|
88 | <span class="mdc-evolution-chip__icon mdc-evolution-chip__icon--trailing">close</span>
|
89 | </button>
|
90 | ```
|
91 |
|
92 | ## API
|
93 |
|
94 | ### CSS classes
|
95 |
|
96 | CSS Class | Description
|
97 | --- | ---
|
98 | `mdc-evolution-chip__action` | Mandatory, for the action root.
|
99 | `mdc-evolution-chip__action--primary` | Mandatory, mutually exclusive with the `*--trailing` root class.
|
100 | `mdc-evolution-chip__action--trailing` | Mandatory, mutually exclusive with the `*--primary` root class.
|
101 | `mdc-evolution-chip__action--presentational` | Optional, used to indicate the action is presentational (not interactive).
|
102 | `mdc-evolution-chip__ripple` | Mandatory, used for the ripple.
|
103 | `mdc-evolution-chip__ripple--primary` | Mandatory for the ripple, mutually exclusive with the `*--trailing` ripple class.
|
104 | `mdc-evolution-chip__ripple--trailing` | Mandatory for the ripple, mutually exclusive with the `*--primary` ripple class.
|
105 | `mdc-evolution-chip__text-label` | Mandatory for primary actions.
|
106 | `mdc-evolution-chip__graphic` | Used for optionally selectable primary actions or primary actions with a leading graphic.
|
107 | `mdc-evolution-chip__icon` | Mandatory for trailing actions, also used for optional leading graphic.
|
108 | `mdc-evolution-chip__icon--primary` | Used for optional leading graphic.
|
109 | `mdc-evolution-chip__checkmark` | Used for optionally selectable primary actions.
|
110 | `mdc-evolution-chip__checkmark-svg` | Used for optionally selectable primary actions.
|
111 | `mdc-evolution-chip__checkmark-path` | Used for optionally selectable primary actions.
|
112 |
|
113 | ### Sass mixins
|
114 |
|
115 | All Sass mixins for actions are provided by the chip Sass.
|
116 |
|
117 | ### `MDCChipAction` methods
|
118 |
|
119 | The `MDCChipAction` is exposed only to be called by the parent [`MDCChip`](../chip). Users should not interact with the `MDCChipAction` component nor rely on any exposed APIs or events.
|
120 |
|
121 | ### `MDCChipActionEvents`
|
122 |
|
123 | These events are only emitted for consumption by the parent [`MDCChip`](../chip). Non-wrapping clients **should not** listen to these events.
|
124 |
|
125 | Event name | Detail | Description
|
126 | --- | --- | ---
|
127 | `MDCChipAction:interaction` | `MDCChipActionInteractionEventDetail` | Consumed in the parent chip `handleActionInteraction` method.
|
128 | `MDCChipAction:navigation` | `MDCChipActionNavigationEventDetail` | Consumed in the parent chip `handleActionNavigation` method.
|
129 |
|
130 | ### `MDCChipActionAdapter`
|
131 |
|
132 | Method Signature | Description
|
133 | --- | ---
|
134 | `emitEvent<D extends object>(eventName: MDCChipActionEvents, eventDetail: D): void` | Emits the given `eventName` with the given `eventDetail`.
|
135 | `focus(): void` | Focuses the action root.
|
136 | `getAttribute(attr: MDCChipActionAttributes): string\|null` | Returns the attribute on the action root or `null` if none exists.
|
137 | `getElementID(): string` | Returns the `[id](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)` of the action root.
|
138 | `removeAttribute(attr: MDCChipActionAttributes): void` | Removes the attribute from the action root.
|
139 | `setAttribute(attr: MDCChipActionAttributes, value: string): void` | Sets the action root attribute to the given `value`
|
140 |
|
141 | ### `MDCChipActionFoundation`
|
142 |
|
143 | `MDCChipActionFoundation` is abstract with concrete subclasses.
|
144 |
|
145 | Method Signature | Description
|
146 | --- | ---
|
147 | `handleClick(): void` | Handles the [click](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event) event.
|
148 | `handleKeydown(event: KeyboardEvent): void` | Handles the [keydown](https://developer.mozilla.org/en-US/docs/Web/API/Element/keydown_event) event.
|
149 | `setDisabled(isDisabled: boolean): void` | Sets the disabled state.
|
150 | `isDisabled(): boolean` | Returns the disabled state.
|
151 | `setFocus(behavior: MDCChipActionFocusBehavior): void` | Set the focus behavior.
|
152 | `isFocusable(): boolean` | Returns whether the action if focusable.
|
153 | `setSelected(isSelected: boolean): void` | Sets the selected state.
|
154 | `isSelected(): boolean` | Returns the selected state.
|
155 | `abstract actionType(): MDCChipActionType` | Returns the type of the action.
|
156 | `abstract isSelectable(): boolean` | Returns whether the action is selectable.
|
157 |
|
158 | #### Subclasses
|
159 |
|
160 | `MDCChipActionFoundation` is subclassed by `MDCChipPrimaryActionFoundation` and `MDCChipTrailingActionFoundation` which encapsulate the behavioral differences between primary and trailing actions. Clients **should not** subclass `MDCChipActionFoundation` themselves. Wrapping clients should provide the correct `MDCChipActionFoundation` subclass for their DOM. The following logic is pulled from the `MDCChipAction` component and should serve as an example of determing which subclass to use.
|
161 |
|
162 | ```ts
|
163 | function init(root: HTMLElement, adapter: MDCChipTrailingActionAdapter): MDCChipTrailingActionFoundation {
|
164 | if (root.classList.contains(CssClasses.TRAILING_ACTION)) {
|
165 | return new MDCChipTrailingActionFoundation(adapter);
|
166 | }
|
167 |
|
168 | // Default to the primary foundation
|
169 | return new MDCChipPrimaryActionFoundation(adapter);
|
170 | }
|
171 | ```
|
172 |
|
173 |
|
174 | ### Usage within frameworks
|
175 |
|
176 | If you are using a JavaScript framework, such as React or Angular, you can create a chip action 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).
|