@material/chips

Chips

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

Design & API Documentation

• Material Design guidelines: Chips
• Demo

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