ContextQMD
Back to Material Components Web

Action

packages/mdc-chips/action/README.md

14.0.08.4 KB
Original Source
<!--docs: title: "Chip action" layout: detail section: components excerpt: "Chip actions represent interactions regions of a chip." iconId: chip path: /catalog/chips/action/ -->

Action

Actions represent discrete interactive regions of a chip. They are only ever used inside of chips.

Basic usage

Note: there's work planned to replace the mdc-evolution-* prefix of chips with the standard mdc-chip-* prefix.

HTML structure

Actions have two varieties: primary and trailing. All chips must have a primary action. Chips may have an optional trailing action.

Primary action

Primary actions often use a <button> as the root.

html
<button class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" type="button" tabindex="0">
  <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
  <span class="mdc-evolution-chip__text-label">Chip label</span>
</button>

Primary actions may also be deletable.

html
<button class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" type="button" tabindex="0" data-mdc-deletable="true">
  <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
  <span class="mdc-evolution-chip__text-label">Chip label</span>
</button>

Primary actions may also be links.

html
<a class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" href="https://google.com" tabindex="0">
  <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
  <span class="mdc-evolution-chip__text-label">Chip label</span>
</a>

Primary actions accept an optional leading graphic.

html
<button class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" type="button" tabindex="0">
  <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
  <span class="mdc-evolution-chip__graphic">
    <span class="mdc-evolution-chip__icon mdc-evolution-chip__icon--primary material-icons">favorite</span>
  </span>
  <span class="mdc-evolution-chip__text-label">Chip label</span>
</button>

Primary actions can also be selectable, implementing the option role. Selectable primary actions require the graphic element with the included checkmark and may also include a leading graphic.

html
<span class="mdc-evolution-chip__action mdc-evolution-chip__action--primary" role="option" aria-selected="false" tabindex="0">
  <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--primary"></span>
  <span class="mdc-evolution-chip__graphic">
    <span class="mdc-evolution-chip__icon mdc-evolution-chip__icon--primary material-icons">favorite</span> <!-- optional -->
    <span class="mdc-evolution-chip__checkmark">
      <svg class="mdc-evolution-chip__checkmark-svg" viewBox="-2 -3 30 30">
        <path class="mdc-evolution-chip__checkmark-path"
              fill="none" stroke="black" d="M1.73,12.91 8.1,19.28 22.79,4.59" />
      </svg>
    </span>
  </span>
  <span class="mdc-evolution-chip__text-label">Chip label</span>
</span>

Trailing action

Trailing actions always use a <button> as the root.

html
<button class="mdc-evolution-chip__action mdc-evolution-chip__action--trailing" type="button" tabindex="-1" data-mdc-deletable="true">
  <span class="mdc-evolution-chip__ripple mdc-evolution-chip__ripple--trailing"></span>
  <span class="mdc-evolution-chip__icon mdc-evolution-chip__icon--trailing">close</span>
</button>

API

CSS classes

CSS ClassDescription
mdc-evolution-chip__actionMandatory, for the action root.
mdc-evolution-chip__action--primaryMandatory, mutually exclusive with the *--trailing root class.
mdc-evolution-chip__action--trailingMandatory, mutually exclusive with the *--primary root class.
mdc-evolution-chip__action--presentationalOptional, used to indicate the action is presentational (not interactive).
mdc-evolution-chip__rippleMandatory, used for the ripple.
mdc-evolution-chip__ripple--primaryMandatory for the ripple, mutually exclusive with the *--trailing ripple class.
mdc-evolution-chip__ripple--trailingMandatory for the ripple, mutually exclusive with the *--primary ripple class.
mdc-evolution-chip__text-labelMandatory for primary actions.
mdc-evolution-chip__graphicUsed for optionally selectable primary actions or primary actions with a leading graphic.
mdc-evolution-chip__iconMandatory for trailing actions, also used for optional leading graphic.
mdc-evolution-chip__icon--primaryUsed for optional leading graphic.
mdc-evolution-chip__checkmarkUsed for optionally selectable primary actions.
mdc-evolution-chip__checkmark-svgUsed for optionally selectable primary actions.
mdc-evolution-chip__checkmark-pathUsed for optionally selectable primary actions.

Sass mixins

All Sass mixins for actions are provided by the chip Sass.

MDCChipAction methods

The MDCChipAction is exposed only to be called by the parent MDCChip. Users should not interact with the MDCChipAction component nor rely on any exposed APIs or events.

MDCChipActionEvents

These events are only emitted for consumption by the parent MDCChip. Non-wrapping clients should not listen to these events.

Event nameDetailDescription
MDCChipAction:interactionMDCChipActionInteractionEventDetailConsumed in the parent chip handleActionInteraction method.
MDCChipAction:navigationMDCChipActionNavigationEventDetailConsumed in the parent chip handleActionNavigation method.

MDCChipActionAdapter

Method SignatureDescription
emitEvent<D extends object>(eventName: MDCChipActionEvents, eventDetail: D): voidEmits the given eventName with the given eventDetail.
focus(): voidFocuses the action root.
getAttribute(attr: MDCChipActionAttributes): string|nullReturns the attribute on the action root or null if none exists.
getElementID(): stringReturns the [id](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id) of the action root.
removeAttribute(attr: MDCChipActionAttributes): voidRemoves the attribute from the action root.
setAttribute(attr: MDCChipActionAttributes, value: string): voidSets the action root attribute to the given value

MDCChipActionFoundation

MDCChipActionFoundation is abstract with concrete subclasses.

Method SignatureDescription
handleClick(): voidHandles the click event.
handleKeydown(event: KeyboardEvent): voidHandles the keydown event.
setDisabled(isDisabled: boolean): voidSets the disabled state.
isDisabled(): booleanReturns the disabled state.
setFocus(behavior: MDCChipActionFocusBehavior): voidSet the focus behavior.
isFocusable(): booleanReturns whether the action if focusable.
setSelected(isSelected: boolean): voidSets the selected state.
isSelected(): booleanReturns the selected state.
abstract actionType(): MDCChipActionTypeReturns the type of the action.
abstract isSelectable(): booleanReturns whether the action is selectable.

Subclasses

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.

ts
function init(root: HTMLElement, adapter: MDCChipTrailingActionAdapter): MDCChipTrailingActionFoundation {
  if (root.classList.contains(CssClasses.TRAILING_ACTION)) {
    return new MDCChipTrailingActionFoundation(adapter);
  }

  // Default to the primary foundation
  return new MDCChipPrimaryActionFoundation(adapter);
}

Usage within frameworks

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.