14.0.0 • Published 5 months ago

@material/chips v14.0.0

Weekly downloads
35,081
License
MIT
Repository
github
Last release
5 months ago

Chips

Chips are compact elements that allow users to enter information, select a choice, filter content, or trigger an action.

Design & API Documentation

Installation

npm install @material/chips

Usage

HTML Structure

<div class="mdc-chip-set">
  <div class="mdc-chip" tabindex="0">
    <div class="mdc-chip__text">Chip content</div>
  </div>
  <div class="mdc-chip" tabindex="0">
    <div class="mdc-chip__text">Chip content</div>
  </div>
  <div class="mdc-chip" tabindex="0">
    <div class="mdc-chip__text">Chip content</div>
  </div>
</div>

Leading and Trailing Icons

You can optionally add a leading icon (i.e. thumbnail) and/or a trailing icon to a chip. To add an icon, add an i element with your preferred icon, give it a class of mdc-chip__icon, and a class of either mdc-chip__icon--leading or mdc-chip__icon--trailing. If you're adding a trailing icon, also set tabindex="0" and role="button" to make it accessible by keyboard and screenreader.

Leading icon
<div class="mdc-chip">
  <i class="material-icons mdc-chip__icon mdc-chip__icon--leading">event</i>
  <div class="mdc-chip__text">Add to calendar</div>
</div>
Trailing icon
<div class="mdc-chip">
  <div class="mdc-chip__text">Jane Smith</div>
  <i class="material-icons mdc-chip__icon mdc-chip__icon--trailing" tabindex="0" role="button">cancel</i>
</div>

Filter Chips

Filter chips are a variant of chips which allow multiple selection from a set of options. When a filter chip is selected, a checkmark appears as the leading icon. If the chip already has a leading icon, the checkmark replaces it. This requires the HTML structure of a filter chip to differ from other chips:

<div class="mdc-chip">
  <div class="mdc-chip__checkmark" >
    <svg class="mdc-chip__checkmark-svg" viewBox="-2 -3 30 30">
      <path class="mdc-chip__checkmark-path" fill="none" stroke="black"
            d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
    </svg>
  </div>
  <div class="mdc-chip__text">Filterable content</div>
</div>

To use a leading icon in a filter chip, put the mdc-chip__icon--leading element before the mdc-chip__checkmark element:

<div class="mdc-chip">
  <i class="material-icons mdc-chip__icon mdc-chip__icon--leading">face</i>
  <div class="mdc-chip__checkmark" >
    <svg class="mdc-chip__checkmark-svg" viewBox="-2 -3 30 30">
      <path class="mdc-chip__checkmark-path" fill="none" stroke="black"
            d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
    </svg>
  </div>
  <div class="mdc-chip__text">Filterable content</div>
</div>

Pre-selected

To display a pre-selected chip, add the class mdc-chip--selected to the root chip element.

<div class="mdc-chip mdc-chip--selected">
  <div class="mdc-chip__text">Add to calendar</div>
</div>

To pre-select filter chips that have a leading icon, also add the class mdc-chip__icon--leading-hidden to the mdc-chip__icon--leading element. This will ensure that the checkmark displaces the leading icon.

<div class="mdc-chip mdc-chip--selected">
  <i class="material-icons mdc-chip__icon mdc-chip__icon--leading mdc-chip__icon--leading-hidden">face</i>
  <div class="mdc-chip__checkmark">
    <svg class="mdc-chip__checkmark-svg" viewBox="-2 -3 30 30">
      <path class="mdc-chip__checkmark-path" fill="none" stroke="black"
            d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
    </svg>
  </div>
  <div class="mdc-chip__text">Filterable content</div>
</div>

CSS Classes

CSS ClassDescription
mdc-chip-setMandatory. Indicates the set that the chip belongs to.
mdc-chip-set--inputOptional. Indicates that the chips in the set are input chips, which enable user input by converting text into chips.
mdc-chip-set--choiceOptional. Indicates that the chips in the set are choice chips, which allow a single selection from a set of options.
mdc-chip-set--filterOptional. Indicates that the chips in the set are filter chips, which allow multiple selection from a set of options.
mdc-chipMandatory.
mdc-chip--selectedOptional. Indicates that the chip is selected.
mdc-chip__textMandatory. Indicates the text content of the chip.
mdc-chip__iconOptional. Indicates an icon in the chip.
mdc-chip__icon--leadingOptional. Indicates a leading icon in the chip.
mdc-chip__icon--leading-hiddenOptional. Hides the leading icon in a filter chip when the chip is selected.
mdc-chip__icon--trailingOptional. Indicates a trailing icon which removes the chip from the DOM. Only use with input chips.
mdc-chip__checkmarkOptional. Indicates the checkmark in a filter chip.
mdc-chip__checkmark-svgMandatory with the use of mdc-chip__checkmark. Indicates the checkmark SVG element in a filter chip.
mdc-chip__checkmark-pathMandatory with the use of mdc-chip__checkmark. Indicates the checkmark SVG path in a filter chip.

NOTE: Every element that has an mdc-chip__icon class must also have either the mdc-chip__icon--leading or mdc-chip__icon--trailing class.

Sass Mixins

To customize the colors of any part of the chip, use the following mixins.

MixinDescription
mdc-chip-set-spacing($gap-size)Customizes the amount of space between each chip in the set
mdc-chip-corner-radius($radius)Customizes the corner radius for a chip
mdc-chip-fill-color-accessible($color)Customizes the background fill color for a chip, and updates the chip's ink, icon and ripple colors to meet accessibility standards
mdc-chip-fill-color($color)Customizes the background fill color for a chip
mdc-chip-ink-color($color)Customizes the text ink color for a chip, and updates the chip's ripple color to match
mdc-chip-selected-ink-color($color)Customizes text ink and ripple color of a chip in the selected state
mdc-chip-outline($width, $style, $color)Customizes the outline properties for a chip
mdc-chip-outline-width($width)Customizes the outline width for a chip
mdc-chip-outline-style($style)Customizes the outline style for a chip
mdc-chip-outline-color($color)Customizes the outline color for a chip
mdc-chip-leading-icon-color($color, $opacity)Customizes the color of a leading icon in a chip, optionally customizes opacity
mdc-chip-trailing-icon-color($color, $opacity, $hover-opacity, $focus-opacity)Customizes the color of a trailing icon in a chip, optionally customizes regular/hover/focus opacities
mdc-chip-leading-icon-size($size)Customizes the size of a leading icon in a chip
mdc-chip-trailing-icon-size($size)Customizes the size of a trailing icon in a chip

NOTE: mdc-chip-set-spacing also sets the amount of space between a chip and the edge of the set it's contained in.

MDCChip and MDCChipSet

The MDC Chips module is comprised of two JavaScript classes:

  • MDCChip defines the behavior of a single chip
  • MDCChipSet defines the behavior of chips within a specific set. For example, chips in an input chip set behave differently from those in a filter chip set.

To use the MDCChip and MDCChipSet classes, import both classes from @material/chips.

MDCChip

Method SignatureDescription
get foundation() => MDCChipFoundationReturns the foundation
isSelected() => booleanProxies to the foundation's isSelected method
remove() => voidDestroys the chip and removes the root element from the DOM
PropertyValue TypeDescription
rippleMDCRippleThe MDCRipple instance for the root element that MDCChip initializes

MDCChipSet

Method SignatureDescription
addChip(text: string, leadingIcon: Element, trailingIcon: Element) => voidCreates a new chip in the chip set with the given text, leading icon, and trailing icon
PropertyValue TypeDescription
chipsArray<MDCChip>An array of the MDCChip objects that represent chips in the set

Adapters: MDCChipAdapter and MDCChipSetAdapter

MDCChipAdapter

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element
removeClass(className: string) => voidRemoves a class from the root element
hasClass(className: string) => booleanReturns true if the root element contains the given class
addClassToLeadingIcon(className: string) => voidAdds a class to the leading icon element
removeClassFromLeadingIcon(className: string) => voidRemoves a class from the leading icon element
eventTargetHasClass(target: EventTarget, className: string) => booleanReturns true if target has className, false otherwise
registerEventHandler(evtType: string, handler: EventListener) => voidRegisters an event listener on the root element
deregisterEventHandler(evtType: string, handler: EventListener) => voidDeregisters an event listener on the root element
registerTrailingIconInteractionHandler(evtType: string, handler: EventListener) => voidRegisters an event listener on the trailing icon element
deregisterTrailingIconInteractionHandler(evtType: string, handler: EventListener) => voidDeregisters an event listener on the trailing icon element
notifyInteraction() => voidEmits a custom event MDCChip:interaction denoting the chip has been interacted with
notifyTrailingIconInteraction() => voidEmits a custom event MDCChip:trailingIconInteraction denoting the chip's trailing icon has been interacted with
notifyRemoval() => voidEmits a custom event MDCChip:removal denoting the chip will be removed
getComputedStyleValue(propertyName: string) => stringReturns the computed property value of the given style property on the root element
setStyleProperty(propertyName: string, value: string) => voidSets the property value of the given style property on the root element

NOTE: The custom events emitted by notifyInteraction and notifyTrailingIconInteraction must pass along the target chip in its event detail, as well as bubble to the parent mdc-chip-set element.

MDCChipSetAdapter

Method SignatureDescription
hasClass(className: string) => booleanReturns whether the chip set element has the given class
registerInteractionHandler(evtType: string, handler: EventListener) => voidRegisters an event handler on the root element for a given event
deregisterInteractionHandler(evtType: string, handler: EventListener) => voidDeregisters an event handler on the root element for a given event
appendChip(text: string, leadingIcon: Element, trailingIcon: Element) => ElementAppends and returns a chip element with the given text, leading icon, and trailing icon
removeChip(chip: MDCChip) => voidRemoves the chip object from the chip set

Foundations: MDCChipFoundation and MDCChipSetFoundation

MDCChipFoundation

Method SignatureDescription
isSelected() => booleanReturns true if the chip is selected
setSelected(selected: boolean) => voidSets the chip's selected state

MDCChipSetFoundation

Method SignatureDescription
addChip(text: string, leadingIcon: Element, trailingIcon: Element) => ElementReturns a new chip element with the given text, leading icon, and trailing icon, added to the root chip set element
select(chipFoundation: MDCChipFoundation) => voidSelects the given chip
deselect(chipFoundation: MDCChipFoundation) => voidDeselects the given chip
14.0.0

2 years ago

13.0.0

3 years ago

12.0.0

3 years ago

11.0.0

3 years ago

10.0.0

3 years ago

9.0.0

3 years ago

8.0.0

3 years ago

7.0.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.0

4 years ago

4.0.0

4 years ago

3.2.0

5 years ago

4.0.0-canary.1

5 years ago

4.0.0-canary.0

5 years ago

4.0.0-alpha.0

5 years ago

3.1.0

5 years ago

3.1.0-alpha.0

5 years ago

3.0.0

5 years ago

3.0.0-alpha.1

5 years ago

3.0.0-alpha.0

5 years ago

2.3.0

5 years ago

2.2.0

5 years ago

3.0.0-0

5 years ago

2.1.1

5 years ago

2.1.0

5 years ago

2.0.0

5 years ago

1.1.1

5 years ago

1.1.0

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago

1.0.0-1

5 years ago

1.0.0-0

5 years ago

0.44.1

5 years ago

0.44.0

5 years ago

0.43.0

5 years ago

0.42.0

5 years ago

0.41.0

5 years ago

0.40.1

6 years ago

0.40.0

6 years ago

0.39.3

6 years ago

0.39.2

6 years ago

0.39.1

6 years ago

0.39.0

6 years ago

0.39.0-0

6 years ago

0.38.1

6 years ago

0.38.0

6 years ago

0.37.1

6 years ago

0.37.0

6 years ago

0.36.1

6 years ago

0.36.0

6 years ago

0.36.0-0

6 years ago

0.35.1

6 years ago

0.35.0

6 years ago

0.34.1

6 years ago

0.34.0

6 years ago

0.33.0

6 years ago

0.32.0

6 years ago

0.31.0

6 years ago

0.30.0

6 years ago