diff --git a/packages/core/src/components/toggle/readme.md b/packages/core/src/components/toggle/readme.md
index beed6a2696..5a07964fba 100644
--- a/packages/core/src/components/toggle/readme.md
+++ b/packages/core/src/components/toggle/readme.md
@@ -1,28 +1,41 @@
 # ion-toggle
 
-A toggle is largely the same thing as an [checkbox](../checkbox),
-however, it also adds the ability to use gestures to swipe the
-toggle on and off.
+Toggles change the state of a single option. Toggles can be switched on or off by pressing or swiping them. They can also be checked programmatically by setting the `checked` property.
+
 
 ```html
+<!-- Default Toggle -->
+<ion-toggle></ion-toggle>
 
+<!-- Disabled Toggle -->
+<ion-toggle disabled></ion-toggle>
+
+<!-- Checked Toggle -->
+<ion-toggle checked></ion-toggle>
+
+<!-- Toggle Colors -->
+<ion-toggle color="primary"></ion-toggle>
+<ion-toggle color="secondary"></ion-toggle>
+<ion-toggle color="danger"></ion-toggle>
+<ion-toggle color="light"></ion-toggle>
+<ion-toggle color="dark"></ion-toggle>
+
+<!-- Toggles in a List -->
 <ion-list>
-
   <ion-item>
     <ion-label>Pepperoni</ion-label>
-    <ion-toggle value="pepperoni" checked></ion-toggle>
+    <ion-toggle slot="end" value="pepperoni" checked></ion-toggle>
   </ion-item>
 
   <ion-item>
     <ion-label>Sausage</ion-label>
-    <ion-toggle value="sausage" disabled></ion-toggle>
+    <ion-toggle slot="end" value="sausage" disabled></ion-toggle>
   </ion-item>
 
   <ion-item>
     <ion-label>Mushrooms</ion-label>
-    <ion-toggle value="mushrooms"></ion-toggle>
+    <ion-toggle slot="end" value="mushrooms"></ion-toggle>
   </ion-item>
-
 </ion-list>
 ```