From b07eef63ad60dec8ce0197f2781abac821bc87b1 Mon Sep 17 00:00:00 2001
From: Brandy Carney <brandy@ionic.io>
Date: Tue, 9 Jan 2018 10:21:44 -0500
Subject: [PATCH] docs(item): add item group docs and update breaking changes

---
 BREAKING.md                                   | 28 +++++-
 .../core/src/components/item-group/readme.md  | 98 +++++++++++++++++++
 2 files changed, 125 insertions(+), 1 deletion(-)

diff --git a/BREAKING.md b/BREAKING.md
index 922368f045..33bfcd1e88 100644
--- a/BREAKING.md
+++ b/BREAKING.md
@@ -13,6 +13,8 @@ A list of the breaking changes introduced in Ionic Angular v4.
 - [Icon](#icon)
 - [Input](#Input)
 - [Item](#item)
+- [Item Divider](#item-divider)
+- [List Header](#list-header)
 - [Nav](#nav)
 - [Option](#option)
 - [Radio](#radio)
@@ -332,7 +334,7 @@ Item should now be written as an `<ion-item>` element. Ionic will determine when
 
 ### Label Required
 
-Previously an `ion-label` would automatically get added to an `ion-item`, `ion-item-divider` and `ion-list-header` if one wasn't provided. Now an `ion-label` should always be added if the component is used to display text.
+Previously an `ion-label` would automatically get added to an `ion-item` if one wasn't provided. Now an `ion-label` should always be added if the component is used to display text.
 
 ```html
 <ion-item>
@@ -378,6 +380,30 @@ These have been renamed to the following:
 </ion-item>
 ```
 
+## Item Divider
+
+### Label Required
+
+Previously an `ion-label` would automatically get added to an `ion-item-divider` if one wasn't provided. Now an `ion-label` should always be added if the component is used to display text.
+
+```html
+<ion-item-divider>
+  <ion-label>Item Divider Label</ion-label>
+</ion-item-divider>
+```
+
+## List Header
+
+### Label Required
+
+Previously an `ion-label` would automatically get added to an `ion-list-header` if one wasn't provided. Now an `ion-label` should always be added if the component is used to display text.
+
+```html
+<ion-list-header>
+  <ion-label>List Header Label</ion-label>
+</ion-list-header>
+```
+
 ## Nav
 
 ### Method renamed
diff --git a/packages/core/src/components/item-group/readme.md b/packages/core/src/components/item-group/readme.md
index 2aba067410..e3271a0f8e 100644
--- a/packages/core/src/components/item-group/readme.md
+++ b/packages/core/src/components/item-group/readme.md
@@ -1,6 +1,104 @@
 # ion-item-group
 
+Item groups are containers that organize similar items together. They can contain item dividers to divide the items into multiple sections.
 
+```html
+<ion-item-group>
+  <ion-item-divider>A</ion-item-divider>
+
+  <ion-item>
+    <ion-label>Angola</ion-label>
+  </ion-item>
+  <ion-item>
+    <ion-label>Argentina</ion-label>
+  </ion-item>
+  <ion-item>
+    <ion-label>Armenia</ion-label>
+  </ion-item>
+</ion-item-group>
+
+<ion-item-group>
+  <ion-item-divider>B</ion-item-divider>
+
+  <ion-item>
+    <ion-label>Bangladesh</ion-label>
+  </ion-item>
+  <ion-item>
+    <ion-label>Belarus</ion-label>
+  </ion-item>
+  <ion-item>
+    <ion-label>Belgium</ion-label>
+  </ion-item>
+</ion-item-group>
+```
+
+They can also be used to group sliding items:
+
+```html
+<ion-item-group>
+  <ion-item-divider>
+    Fruits
+  </ion-item-divider>
+
+  <ion-item-sliding>
+    <ion-item>
+      <ion-label>
+        <h3>Grapes</h3>
+      </ion-label>
+    </ion-item>
+    <ion-item-options>
+      <ion-item-option>
+        Favorite
+      </ion-item-option>
+    </ion-item-options>
+  </ion-item-sliding>
+
+  <ion-item-sliding>
+    <ion-item>
+      <ion-label>
+        <h3>Apples</h3>
+      </ion-label>
+    </ion-item>
+    <ion-item-options>
+      <ion-item-option>
+        Favorite
+      </ion-item-option>
+    </ion-item-options>
+  </ion-item-sliding>
+</ion-item-group>
+
+<ion-item-group>
+  <ion-item-divider>
+    Vegetables
+  </ion-item-divider>
+
+  <ion-item-sliding>
+    <ion-item>
+      <ion-label>
+        <h3>Carrots</h3>
+      </ion-label>
+    </ion-item>
+    <ion-item-options>
+      <ion-item-option>
+        Favorite
+      </ion-item-option>
+    </ion-item-options>
+  </ion-item-sliding>
+
+  <ion-item-sliding>
+    <ion-item>
+      <ion-label>
+        <h3>Celery</h3>
+      </ion-label>
+    </ion-item>
+    <ion-item-options>
+      <ion-item-option>
+        Favorite
+      </ion-item-option>
+    </ion-item-options>
+  </ion-item-sliding>
+</ion-item-group>
+```
 
 <!-- Auto Generated Below -->