material-components_material-components-ios/components/Chips

Chips

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

Contents

• Using chips
• Input chips
• Choice chips
• Filter chips
• Action chips
• Theming chips

Using chips

Chips allow users to enter information, make selections, filter content, or trigger actions. While buttons are expected to appear consistently and with familiar calls to action, chips should appear dynamically as a group of multiple interactive elements.

Installing chips

Add the following to your Podfile:

pod 'MaterialComponents/Chips'

Then, run the following command:

pod install

Importing chips

To import the component:

Swift

import MaterialComponents.MaterialChips

Objective-C

#import "MaterialChips.h"

Usage

Create and add a single chip to your view controller just like any other UIView.

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

Making chips accessible

Always verify that your chips meet minimum touch requirements, as defined by either Apple's Human Interface Guidelines or Material. Material recommends a 44x44 minimum touch target.

Remember to set any relevant accessibilityLabels or accessibilityTraits, especially if you are not satisfied with default system values.

Ink ripple animation

Chips display animated ink splashes when the user presses the chip. Note that if you have a background color set for the highlighted state the ink animation will occur on top of that color.

Stateful properties

Like UIButton, MDCChipView provides many state-dependant accessors. These methods allow you to set the background color, title color, border style, and elevation, both for individual states and combinations of states. If no value is set for a given state, the normal value will used.

Selected Image View

Setting the image for the selectedImageView is optional but can help clarify that a chip is selected. This image will only appear when the chip is selected. If you have an image set on the standard imageView, then the selectedImageView will appear on top of it. 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 that determine a chip's layout: 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.

Adjusting chip sizes after changing the label

If the label of a chip in a collection view can be changed dynamically (e.g. in reaction to a user's tap), then you may notice that the chip's frame does not automatically update to accomodate the new size of the chip's label. To force your chip to update its layout when this happens you can invoke invalidateIntrinsicContentSize on the chip view. For example:

Swift

chipView.invalidateIntrinsicContentSize()

Objective-C

[chipView invalidateIntrinsicContentSize];

Types

There are four types of chips:

1. input (text entry)
2. choice
3. filter
4. action

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.

We currently provide an implementation of Input Chips called MDCChipField.

MDCChipField *chipField = [[MDCChipField alloc] init];
chipField.delegate = self;
chipField.textField.placeholderLabel.text = @"This is a chip field.";
chipField.showChipsDeleteButton = true
[chipField sizeToFit];
[self.view addSubview:chipField];

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.

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.

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.

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.

Anatomy and key properties

The following is an anatomy diagram of a chip:

1. Container
2. Thumbnail (optional)
3. Text
4. Remove icon (optional)

Container attributes

	Attribute	Related method(s)	Default value
Color	N/A	-setBackgroundColor:forState: -backgroundColorForState:	On surface color at 12% opacity
Ripple color	N/A	-setRippleColor:forState: -rippleColorForState:	White at 14% opacity
Stroke width	N/A	-setBorderWidth:forState: -borderWidthForState:	0
Stroke color	N/A	-setBorderColor:forState: -borderColorForState:	nil
Min height	minimumSize	N/A	{ 0, 32 }
Padding	contentPadding	N/A	{ 4, 4, 4, 4 }
Min touch target	centerVisibleArea, visibleAreaInsets	N/A	NO, { 0, 0, 0, 0 }

Thumbnail attributes

Chip icon

	Attribute	Related method(s)	Default value
Icon	imageView, selectedImageView	N/A	nil
Padding	imagePadding, accessoryPadding	N/A	{ 0, 0, 0, 0 }, { 0, 0, 0, 0 }

Text attributes

	Attribute	Related method(s)	Default value
Text label	titleLabel	N/A	N/A
Color	N/A	-setTitleColor:forState: -titleColorForState:	On surface color at 87% opacity
Typography	titleFont	N/A	Body 2
Padding	titlePadding	N/A	{ 3, 8, 4, 8 }

Theming chips

MDCChipView supports Material Theming using a Container Scheme. There are two variants for Material Theming of an MDCChipView, which are the default theme and the outlined theme.

Below is a Chip collection with the Shrine theme applied to it.

Swift

// Import the Chips Theming Extensions module
import MaterialComponents.MaterialChips_MaterialTheming
 ...
 // Create or use your app's Container Scheme
let containerScheme = MDCContainerScheme()
 // Theme the chip with either default theme
chip.applyTheme(withScheme: containerScheme)
 // Or outlined theme
chip.applyOutlinedTheme(withScheme: containerScheme)

Objective-C

// Import the Tabs Theming Extensions header
#import <MaterialComponents/MaterialChips+MaterialTheming.h>
 ...
 // Create or use your app's Container Scheme
MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init];
 // Theme the chip with either default theme
[self.chip applyThemeWithScheme:containerScheme];
 // Or outlined theme
[self.chip applyOutlinedThemeWithScheme:containerScheme];