material-components_material-components-ios/components/Chips

Chips

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

Design & API documentation

• Material Design guidelines: Chips
• Class: MDCChipCollectionViewFlowLayout
• Class: MDCChipCollectionViewCell
• Class: MDCChipField
• Class: MDCChipView
• Protocol: MDCChipFieldDelegate
• Enumeration: Enumerations
• Enumeration: MDCChipFieldDelimiter

Table of contents

• Installation
  • Installation with CocoaPods
  • Importing
• Chips Collections
  • Input Chips
  • Choice Chips
  • Filter Chips
  • Action Chips
• Tips
  • Ink ripple animation
  • Stateful properties
  • Selected Image View
  • Padding
• Behavioral flags
  • Accessibility
• Examples
  • Create a single Chip
• Extensions
  • Chip Color Theming
  • Typography Theming
  • Shape Theming

---

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.

---

Behavioral flags

If within your MDCChipField you want chips that can be deleted follow these steps.

Accessibility

Enabling this flag will add 24x24 touch targets within the chip view. This goes against Google's recommended 48x48 touch targets. We recommend if you enable this behavior your associate it with a MDCSnackbar or MDCDialog to confirm allow the user to confirm their behavior.

Swift

let chipField = MDCChipField()
chipField.showChipsDeleteButton = true

Objective-C

MDCChipField *chipField = [[MDCChipField alloc] init];
chipField.showChipsDeleteButton = YES;

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

Shape Theming

You can theme a chip with your app's shape scheme using the ShapeThemer extension.

You must first add the ShapeThemer extension to your project:

pod 'MaterialComponents/Chips+ShapeThemer'

Swift

// Step 1: Import the ShapeThemer extension
import MaterialComponents.MaterialChips_ShapeThemer

// Step 2: Create or get a shape scheme
let shapeScheme = MDCShapeScheme()

// Step 3: Apply the shape scheme to your component
MDCChipViewShapeThemer.applyShapeScheme(shapeScheme, to: component)

Objective-C

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

// Step 2: Create or get a shape scheme
id<MDCShapeScheming> shapeScheme = [[MDCShapeScheme alloc] init];

// Step 3: Apply the shape scheme to your component
[MDCChipViewShapeThemer applyShapeScheme:shapeScheme
     toChipView:component];