Material Design

Chips

Open bugs badge

Chips are compact elements that represent an input, attribute, or action.

Design & API documentation

Table of contents


Installation

Installation with CocoaPods

Add the following to your Podfile:

pod 'MaterialComponents/Chips'

Then, run the following command:

pod install

Importing

To import the component:

Swift

import MaterialComponents.MaterialChips

Objective-C

#import "MaterialChips.h"

Chips Collections

Material design suggest the usage of chips collection in four context: Input Chips, Choice Chips, Filter Chips, and Action Chips.

Input Chips

Input chips represent a complex piece of information in compact form, such as an entity (person, place, or thing) or text. They enable user input and verify that input by converting text into chips.

Implementation

We currently provide an implementation of Input Chips called MDCChipField.

Choice Chips

Choice chips allow selection of a single chip from a set of options.

Choice chips clearly delineate and display options in a compact area. They are a good alternative to toggle buttons, radio buttons, and single select menus.

Implementation

It is easiest to create choice Chips using a UICollectionView:

  • Use MDCChipCollectionViewFlowLayout as the UICollectionView layout:
 MDCChipCollectionViewFlowLayout *layout = [[MDCChipCollectionViewFlowLayout alloc] init];
  _collectionView = [[UICollectionView alloc] initWithFrame:CGRectZero collectionViewLayout:layout];
  • Leave the default UICollectionView selection setting (single selection).
  • Use MDCChipCollectionViewCell as UICollectionView cells. (MDCChipCollectionViewCell manages the state of the chip based on selection state of UICollectionView automatically)
  - (void)loadView {
    [super loadView];
    …
    [_collectionView registerClass:[MDCChipCollectionViewCell class]
        forCellWithReuseIdentifier:@"identifier"];
    ...
   }

  - (__kindof UICollectionViewCell *)collectionView:(UICollectionView *)collectionView
                             cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    MDCChipCollectionViewCell *cell =
        [collectionView dequeueReusableCellWithReuseIdentifier:@"identifier" forIndexPath:indexPath];
    MDCChipView *chipView = cell.chipView;
    // configure the chipView
     return cell;
  }
  • Use UICollectionViewDelegate methods collectionView:didSelectItemAtIndexPath: for reacting to new choices.

  • Use UICollectionView selectItemAtIndexPath:animated:scrollPosition: method to edit choice selection programmatically.

Filter Chips

Filter chips use tags or descriptive words to filter content.

Filter chips clearly delineate and display options in a compact area. They are a good alternative to toggle buttons or checkboxes.

Implementation

It is easiest to create filter Chips using a UICollectionView:

  • Use MDCChipCollectionViewFlowLayout as the UICollectionView layout:
 MDCChipCollectionViewFlowLayout *layout = [[MDCChipCollectionViewFlowLayout alloc] init];
  _collectionView = [[UICollectionView alloc] initWithFrame:CGRectZero collectionViewLayout:layout];
  • Allow multi cell selection in the UICollectionView:
  collectionView.allowsMultipleSelection = YES; 
  • Use MDCChipCollectionViewCell as UICollectionView cells. (MDCChipCollectionViewCell manages the state of the chip based on selection state of UICollectionView automatically)
  - (void)loadView {
    [super loadView];
    …
    [_collectionView registerClass:[MDCChipCollectionViewCell class]
        forCellWithReuseIdentifier:@"identifier"];
    ...
   }

  - (__kindof UICollectionViewCell *)collectionView:(UICollectionView *)collectionView
                             cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    MDCChipCollectionViewCell *cell =
        [collectionView dequeueReusableCellWithReuseIdentifier:@"identifier" forIndexPath:indexPath];
    MDCChipView *chipView = cell.chipView;
    // configure the chipView
     return cell;
  }
  • Use UICollectionViewDelegate methods collectionView:didSelectItemAtIndexPath: and collectionView:didDeselectItemAtIndexPath: for reacting to filter changes.

  • Use UICollectionView deselectItemAtIndexPath:animated: and selectItemAtIndexPath:animated:scrollPosition: methods to edit filter selection in code.

Action Chips

Action chips offer actions related to primary content. They should appear dynamically and contextually in a UI.

An alternative to action chips are buttons, which should appear persistently and consistently.

Implementation

It is easiest to create action Chips using a UICollectionView:

  • Use MDCChipCollectionViewFlowLayout as the UICollectionView layout:
 MDCChipCollectionViewFlowLayout *layout = [[MDCChipCollectionViewFlowLayout alloc] init];
  _collectionView = [[UICollectionView alloc] initWithFrame:CGRectZero collectionViewLayout:layout];
  • Leave the default UICollectionView selection setting (single selection).
  • Use MDCChipCollectionViewCell as UICollectionView cells. (MDCChipCollectionViewCell manages the state of the chip based on selection state of UICollectionView automatically)
  - (void)loadView {
    [super loadView];
    …
    [_collectionView registerClass:[MDCChipCollectionViewCell class]
        forCellWithReuseIdentifier:@"identifier"];
    ...
   }

  - (__kindof UICollectionViewCell *)collectionView:(UICollectionView *)collectionView
                             cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    MDCChipCollectionViewCell *cell =
        [collectionView dequeueReusableCellWithReuseIdentifier:@"identifier" forIndexPath:indexPath];
    MDCChipView *chipView = cell.chipView;
    // configure the chipView
     return cell;
  }
  • Make sure that MDCChipCollectionViewCell does not stay in selected state
 - (void)collectionView:(UICollectionView *)collectionView didSelectItemAtIndexPath:(NSIndexPath *)indexPath {
    // For action chips, we never want the chip to stay in selected state.
    // Other possible apporaches would be relying on theming or Customizing collectionViewCell
    // selected state.
    [collectionView deselectItemAtIndexPath:indexPath animated:NO];
    // Trigger the action
  }
  • Use UICollectionViewDelegate method collectionView:didSelectItemAtIndexPath: to Trigger the action.

Tips

Ink ripple animation

Chips display animated ink splashes when the user presses the chip. Keep in mind this will appear on top of your ‘highlighted’ backgroundColor.

Stateful properties

Like UIButton, Material Chips have many state-dependant properties. Set your background color, title color, border style, and elevation for each of their states. If you don’t set a value for a specific state it will fall back to whatever value has been provided for the Normal state. Don’t forget that you’ll also need to set values for the combined states, such as Highlighted | Selected.

Selected Image View

In order to make it as clear as possible a chip has been selected, you can optionally set the image of the selectedImageView. This image will only appear when the chip is selected. If you have a image set on the standard imageView, then the selectedImageView will appear on top. Otherwise you’ll need to resize the chip to show the selected image. See the Filter chip example to see this in action.

Padding

There are 4 padding properties which control how a chip is laid out. One for each of the chip’s subviews (imageView and selectedImageView share one padding property), and one which wraps all the others (contentPadding). This is useful so that you can set each of the padding properties to ensure your chips look correct whether or not they have an image and/or accessory view. The chip uses these property to determine intrinsicContentSize and sizeThatFits.


Examples

Create a single Chip

Swift

let chipView = MDCChipView()
chipView.titleLabel.text = "Tap me"
chipView.setTitleColor(UIColor.red, for: .selected)
chipView.sizeToFit()
chipView.addTarget(self, action: #selector(tap), for: .touchUpInside)
self.view.addSubview(chipView)

Objective-C

MDCChipView *chipView = [[MDCChipView alloc] init];
chipView.titleLabel.text = @"Tap me";
[chipView setTitleColor:[UIColor redColor] forState:UIControlStateSelected];
[chipView sizeToFit];
[chipView addTarget:self
               action:@selector(tap:)
     forControlEvents:UIControlEventTouchUpInside];
[self.view addSubview:chipView];

Extensions

Chip Color Theming

You can theme a chip with your app’s color scheme using the ColorThemer extension.

You must first add the Color Themer extension to your project:

pod 'MaterialComponents/Chips+ColorThemer'

Swift

// Step 1: Import the ColorThemer extension
import MaterialComponents.MaterialChips_ColorThemer

// Step 2: Create or get a color scheme
let colorScheme = MDCSemanticColorScheme()

// Step 3: Apply the color scheme to your component
MDCChipViewColorThemer.applySemanticColorScheme(colorScheme, to: component)

Objective-C

// Step 1: Import the ColorThemer extension
#import "MaterialChips+ColorThemer.h"

// Step 2: Create or get a color scheme
id<MDCColorScheming> colorScheme = [[MDCSemanticColorScheme alloc] init];

// Step 3: Apply the color scheme to your component
[MDCChipViewColorThemer applySemanticColorScheme:colorScheme
     toChipView:component];

Typography Theming

You can theme a chip with your app’s typography scheme using the TypographyThemer extension.

You must first add the Typography Themer extension to your project:

pod 'MaterialComponents/Chips+TypographyThemer'

Swift

// Step 1: Import the TypographyThemer extension
import MaterialComponents.MaterialChips_TypographyThemer

// Step 2: Create or get a typography scheme
let typographyScheme = MDCTypographyScheme()

// Step 3: Apply the typography scheme to your component
MDCChipViewTypographyThemer.applyTypographyScheme(typographyScheme, to: component)

Objective-C

// Step 1: Import the TypographyThemer extension
#import "MaterialChips+TypographyThemer.h"

// Step 2: Create or get a typography scheme
id<MDCTypographyScheming> typographyScheme = [[MDCTypographyScheme alloc] init];

// Step 3: Apply the typography scheme to your component
[MDCChipViewTypographyThemer applyTypographyScheme:colorScheme
     toChipView:component];