diff --git a/packages/core/src/components/chip/readme.md b/packages/core/src/components/chip/readme.md
index 2b841f7999..8334ece34e 100644
--- a/packages/core/src/components/chip/readme.md
+++ b/packages/core/src/components/chip/readme.md
@@ -1,6 +1,6 @@
 # ion-chip
 
-Chips represent complex entities in small blocks, such as a contact.
+Chips represent complex entities in small blocks, such as a contact. A chip can contain several different elements such as avatars, text, buttons, and icons.
 
 
 ```html
@@ -16,14 +16,6 @@ Chips represent complex entities in small blocks, such as a contact.
   <ion-label color="dark">Secondary w/ Dark label</ion-label>
 </ion-chip>
 
-<ion-chip color="warning">
-  <ion-label>Warning</ion-label>
-</ion-chip>
-
-<ion-chip color="danger">
-  <ion-label>Danger</ion-label>
-</ion-chip>
-
 <ion-chip>
   <ion-icon name="pin"></ion-icon>
   <ion-label>Default</ion-label>
@@ -35,38 +27,28 @@ Chips represent complex entities in small blocks, such as a contact.
 </ion-chip>
 
 <ion-chip>
-  <ion-avatar>
-    <img src="assets/img/my-img.png">
-  </ion-avatar>
-  <ion-label>Default</ion-label>
-</ion-chip>
-```
-
-
-```html
-<ion-chip #chip1>
-  <ion-label>Default</ion-label>
-  <ion-button clear color="light" (click)="delete(chip1)">
+  <ion-label>Button Chip</ion-label>
+  <ion-chip-button fill="clear" color="light">
     <ion-icon name="close-circle"></ion-icon>
-  </ion-button>
+  </ion-chip-button>
 </ion-chip>
 
-<ion-chip #chip2>
+<ion-chip>
   <ion-icon name="pin" color="primary"></ion-icon>
-  <ion-label>With Icon</ion-label>
-  <ion-button (click)="delete(chip2)">
+  <ion-label>Icon Chip</ion-label>
+  <ion-chip-button>
     <ion-icon name="close"></ion-icon>
-  </ion-button>
+  </ion-chip-button>
 </ion-chip>
 
-<ion-chip #chip3>
+<ion-chip>
   <ion-avatar>
-    <img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
+    <img src="https://gravatar.com/avatar/dba6bae8c566f9d4041fb9cd9ada7741?d=identicon&f=y">
   </ion-avatar>
-  <ion-label>With Avatar</ion-label>
-  <ion-button clear color="dark" (click)="delete(chip3)">
+  <ion-label>Avatar Chip</ion-label>
+  <ion-chip-button fill="clear" color="dark">
     <ion-icon name="close-circle"></ion-icon>
-  </ion-button>
+  </ion-chip-button>
 </ion-chip>
 ```