Material Design

Chips

Chips screenshot

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

Basic Usage

HTML Structure

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

Styles

@import "@material/chips/mdc-chips";

JavaScript Instantiation

import {MDCChipSet} from '@material/chips';

const chipSet = new MDCChipSet(document.querySelector('.mdc-chip-set'));

See Importing the JS component for more information on how to import JavaScript.

Variants

Leading and Trailing Icons

You can optionally add a leading icon (i.e. thumbnail) and/or a trailing “remove” 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.

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

A trailing icon comes with the functionality to remove the chip from the set. If you’re adding a trailing icon, also set tabindex="0" and role="button" to make it accessible by keyboard and screenreader. Trailing icons should only be added to input chips.

<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>

Choice Chips

Choice chips are a variant of chips which allow single selection from a set of options. To define a set of chips as choice chips, add the class mdc-chip-set--choice to the chip set element.

Filter Chips

Filter chips are a variant of chips which allow multiple selection from a set of options. To define a set of chips as filter chips, add the class mdc-chip-set--filter to the chip set element. 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>

Input Chips

Input chips are a variant of chips which enable user input by converting text into chips. To define a set of chips as input chips, add the class mdc-chip-set--input to the chip set element. You’d also want to add an event listener that calls addChip on the MDCChipSet to convert text to a chip. More information can be found in the “MDCChip Properties and Methods” section below.

Pre-selected

To display a pre-selected filter or choice 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>

Style Customization

CSS Classes

CSS Class Description
mdc-chip-set Mandatory. Indicates the set that the chip belongs to.
mdc-chip-set--input Optional. Indicates that the chips in the set are input chips, which enable user input by converting text into chips.
mdc-chip-set--choice Optional. Indicates that the chips in the set are choice chips, which allow a single selection from a set of options.
mdc-chip-set--filter Optional. Indicates that the chips in the set are filter chips, which allow multiple selection from a set of options.
mdc-chip Mandatory.
mdc-chip--selected Optional. Indicates that the chip is selected.
mdc-chip__text Mandatory. Indicates the text content of the chip.
mdc-chip__icon Optional. Indicates an icon in the chip.
mdc-chip__icon--leading Optional. Indicates a leading icon in the chip.
mdc-chip__icon--leading-hidden Optional. Hides the leading icon in a filter chip when the chip is selected.
mdc-chip__icon--trailing Optional. Indicates a trailing icon which removes the chip from the DOM. Only use with input chips.
mdc-chip__checkmark Optional. Indicates the checkmark in a filter chip.
mdc-chip__checkmark-svg Mandatory with the use of mdc-chip__checkmark. Indicates the checkmark SVG element in a filter chip.
mdc-chip__checkmark-path Mandatory 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

Mixin Description
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 Properties and Methods

The MDC Chips package is composed 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 Signature Description
get foundation() => MDCChipFoundation Returns the foundation
isSelected() => boolean Proxies to the foundation’s isSelected method
remove() => void Destroys the chip and removes the root element from the DOM
Property Value Type Description
ripple MDCRipple The MDCRipple instance for the root element that MDCChip initializes

MDCChipSet

Method Signature Description
addChip(text: string, leadingIcon: Element, trailingIcon: Element) => void Creates a new chip in the chip set with the given text, leading icon, and trailing icon
Property Value Type Description
chips Array<MDCChip> An array of the MDCChip objects that represent chips in the set

Usage within Web Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create Chips 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.

Adapters: MDCChipAdapter and MDCChipSetAdapter

MDCChipAdapter

Method Signature Description
addClass(className: string) => void Adds a class to the root element
removeClass(className: string) => void Removes a class from the root element
hasClass(className: string) => boolean Returns true if the root element contains the given class
addClassToLeadingIcon(className: string) => void Adds a class to the leading icon element
removeClassFromLeadingIcon(className: string) => void Removes a class from the leading icon element
eventTargetHasClass(target: EventTarget, className: string) => boolean Returns true if target has className, false otherwise
registerEventHandler(evtType: string, handler: EventListener) => void Registers an event listener on the root element
deregisterEventHandler(evtType: string, handler: EventListener) => void Deregisters an event listener on the root element
registerTrailingIconInteractionHandler(evtType: string, handler: EventListener) => void Registers an event listener on the trailing icon element
deregisterTrailingIconInteractionHandler(evtType: string, handler: EventListener) => void Deregisters an event listener on the trailing icon element
notifyInteraction() => void Emits a custom event MDCChip:interaction denoting the chip has been interacted with
notifyTrailingIconInteraction() => void Emits a custom event MDCChip:trailingIconInteraction denoting the chip’s trailing icon has been interacted with
notifyRemoval() => void Emits a custom event MDCChip:removal denoting the chip will be removed
getComputedStyleValue(propertyName: string) => string Returns the computed property value of the given style property on the root element
setStyleProperty(propertyName: string, value: string) => void Sets 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 Signature Description
hasClass(className: string) => boolean Returns whether the chip set element has the given class
registerInteractionHandler(evtType: string, handler: EventListener) => void Registers an event handler on the root element for a given event
deregisterInteractionHandler(evtType: string, handler: EventListener) => void Deregisters an event handler on the root element for a given event
appendChip(text: string, leadingIcon: Element, trailingIcon: Element) => Element Appends and returns a chip element with the given text, leading icon, and trailing icon
removeChip(chip: MDCChip) => void Removes the chip object from the chip set

Foundations: MDCChipFoundation and MDCChipSetFoundation

MDCChipFoundation

Method Signature Description
isSelected() => boolean Returns true if the chip is selected
setSelected(selected: boolean) => void Sets the chip’s selected state

MDCChipSetFoundation

Method Signature Description
addChip(text: string, leadingIcon: Element, trailingIcon: Element) => Element Returns a new chip element with the given text, leading icon, and trailing icon, added to the root chip set element
select(chipFoundation: MDCChipFoundation) => void Selects the given chip
deselect(chipFoundation: MDCChipFoundation) => void Deselects the given chip