diff --git a/components/Chips/.vars b/components/Chips/.vars
index e7d2fde6368..2bc1fed23ff 100644
--- a/components/Chips/.vars
+++ b/components/Chips/.vars
@@ -1,8 +1,9 @@
component=Chips
-component_name=Chip
+component_name=Chips
a_component_name=a chip
root_path=/catalog/chips
icon_id=chip
color_themer_api=MDCChipViewColorThemer
typography_themer_api=MDCChipViewTypographyThemer
themer_parameter_name=ChipView
+short_description=Chips represent complex entities in small blocks, such as a contact.
diff --git a/components/Chips/README.md b/components/Chips/README.md
index 2025f9f8456..17a0df4b8a8 100644
--- a/components/Chips/README.md
+++ b/components/Chips/README.md
@@ -8,37 +8,50 @@ path: /catalog/chips/
api_doc_root: true
-->
+
+
# Chips
Chips represent complex entities, such as a contact, in small blocks.
-## Design & API Documentation
+## Design & API documentation
-## Extensions
-
-
+## Table of contents
+
+- [Installation](#installation)
+ - [Installation with CocoaPods](#installation-with-cocoapods)
+ - [Importing](#importing)
+- [Chips Collections](#chips-collections)
+ - [Input Chips](#input-chips)
+ - [Choice Chips](#choice-chips)
+ - [Filter Chips](#filter-chips)
+ - [Action Chips](#action-chips)
+- [Tips](#tips)
+ - [Ink ripple animation](#ink-ripple-animation)
+ - [Stateful properties](#stateful-properties)
+ - [Selected Image View](#selected-image-view)
+ - [Padding](#padding)
+- [Examples](#examples)
+ - [Create a single Chip](#create-a-single-chip)
+- [Extensions](#extensions)
+ - [Chip Color Theming](#chip-color-theming)
+ - [Typography Theming](#typography-theming)
- - -
## Installation
-### Requirements
-
-- Xcode 8.0 or higher.
-- iOS SDK version 7.0 or higher.
+
### Installation with CocoaPods
-To add this component to your Xcode project using CocoaPods, add the following to your `Podfile`:
+Add the following to your `Podfile`:
-```
+```bash
pod 'MaterialComponents/Chips'
```
@@ -49,28 +62,28 @@ Then, run the following command:
pod install
```
-- - -
-
-## Importing
+### Importing
-Before using Chips, you'll need to import them:
+To import the component:
-### Swift
+#### Swift
```swift
import MaterialComponents.MaterialChips
```
-### Objective-C
+#### Objective-C
```objc
#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
@@ -235,7 +248,10 @@ It is easiest to create action Chips using a `UICollectionView`:
- - -
-## How to use a chip
+
+## Tips
+
+
### Ink ripple animation
Chips display animated ink splashes when the user presses the chip. Keep in mind this will appear on
@@ -261,17 +277,13 @@ the others (`contentPadding`). This is useful so that you can set each of the pa
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`.
-### Style Variants
-MDCChipViewThemer exposes apis to theme MDCChipView instances as either a default or outlined
-variant. An outlined variant behaves identically to a default styled chipview, but differs in its
-coloring and in that it has a stroked border. Use 'applyScheme:toChipView:' to style an instance
-with default values and 'applyOutlinedVariantWithScheme:toChipView:' to style an instance with
-the outlined values.
-
- - -
+
## Examples
+
+
### Create a single Chip
@@ -298,3 +310,88 @@ chipView.titleLabel.text = @"Tap me";
[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:
+
+```bash
+pod 'MaterialComponents/Chips+Extensions/ColorThemer'
+```
+
+
+#### Swift
+```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
+
+```objc
+// Step 1: Import the ColorThemer extension
+#import "MaterialChips+ColorThemer.h"
+
+// Step 2: Create or get a color scheme
+id 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:
+
+```bash
+pod 'MaterialComponents/Chips+Extensions/TypographyThemer'
+```
+
+
+#### Swift
+```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
+
+```objc
+// Step 1: Import the TypographyThemer extension
+#import "MaterialChips+TypographyThemer.h"
+
+// Step 2: Create or get a typography scheme
+id typographyScheme = [[MDCTypographyScheme alloc] init];
+
+// Step 3: Apply the typography scheme to your component
+[MDCChipViewTypographyThemer applyTypographyScheme:colorScheme
+ toChipView:component];
+```
+
+
diff --git a/components/Chips/docs/README.md b/components/Chips/docs/README.md
new file mode 100644
index 00000000000..f35c9ede1cd
--- /dev/null
+++ b/components/Chips/docs/README.md
@@ -0,0 +1,33 @@
+# Chips
+
+Chips represent complex entities, such as a contact, in small blocks.
+
+## Design & API documentation
+
+* [Material Design guidelines: Chips](https://material.io/go/design-chips)
+
+
+
+- - -
+
+## Installation
+
+- [Typical installation](../../../docs/component-installation.md)
+
+## Chips Collections
+
+- [Chips Collections](chips-collections.md)
+
+## Tips
+
+- [Tips](tips.md)
+
+## Examples
+
+- [Examples](Examples.md)
+
+## Extensions
+
+- [Color Theming](color-theming.md)
+
+- [Typography Theming](typography-theming.md)
diff --git a/components/Chips/docs/chips-collections.md b/components/Chips/docs/chips-collections.md
new file mode 100644
index 00000000000..a7c8a39d392
--- /dev/null
+++ b/components/Chips/docs/chips-collections.md
@@ -0,0 +1,163 @@
+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:
+
+ ```objc
+ 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)
+
+
+ ```objc
+ - (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:
+
+ ```objc
+ MDCChipCollectionViewFlowLayout *layout = [[MDCChipCollectionViewFlowLayout alloc] init];
+ _collectionView = [[UICollectionView alloc] initWithFrame:CGRectZero collectionViewLayout:layout];
+ ```
+
+
+ - Allow multi cell selection in the `UICollectionView`:
+
+ ```objc
+ collectionView.allowsMultipleSelection = YES;
+ ```
+
+ - Use `MDCChipCollectionViewCell` as `UICollectionView` cells. (`MDCChipCollectionViewCell` manages the state of the chip based on selection state of `UICollectionView` automatically)
+
+
+ ```objc
+ - (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:
+
+ ```objc
+ 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)
+
+
+ ```objc
+ - (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
+
+
+ ```objc
+ - (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.
+
+- - -
diff --git a/components/Chips/docs/color-theming.md b/components/Chips/docs/color-theming.md
index ec4602da98c..1b85223607f 100644
--- a/components/Chips/docs/color-theming.md
+++ b/components/Chips/docs/color-theming.md
@@ -1,13 +1,4 @@
-
-
-# Chip Color Theming
+### Chip Color Theming
You can theme a chip with your app's color scheme using the ColorThemer extension.
@@ -17,8 +8,6 @@ You must first add the Color Themer extension to your project:
pod 'MaterialComponents/Chips+Extensions/ColorThemer'
```
-## Example code
-
#### Swift
```swift
diff --git a/components/Chips/docs/examples.md b/components/Chips/docs/examples.md
new file mode 100644
index 00000000000..949b2183229
--- /dev/null
+++ b/components/Chips/docs/examples.md
@@ -0,0 +1,26 @@
+### Create a single Chip
+
+
+#### Swift
+```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
+
+```objc
+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];
+```
+
diff --git a/components/Chips/docs/tips.md b/components/Chips/docs/tips.md
new file mode 100644
index 00000000000..79b2b78cf8c
--- /dev/null
+++ b/components/Chips/docs/tips.md
@@ -0,0 +1,25 @@
+### 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`.
+
+- - -
diff --git a/components/Chips/docs/typography-theming.md b/components/Chips/docs/typography-theming.md
index 6d45fd1fe36..5a023a93135 100644
--- a/components/Chips/docs/typography-theming.md
+++ b/components/Chips/docs/typography-theming.md
@@ -1,13 +1,4 @@
-
-
-# Chip Typography Theming
+### Typography Theming
You can theme a chip with your app's typography scheme using the TypographyThemer extension.
@@ -17,8 +8,6 @@ You must first add the Typography Themer extension to your project:
pod 'MaterialComponents/Chips+Extensions/TypographyThemer'
```
-## Example code
-
#### Swift
```swift