diff --git a/core/src/components/fab/readme.md b/core/src/components/fab/readme.md
index 54bbe7bf71..4f45a546c1 100644
--- a/core/src/components/fab/readme.md
+++ b/core/src/components/fab/readme.md
@@ -1,110 +1,15 @@
 # ion-fab
 
-Fabs are container elements that contain one or more fab buttons. They should be placed in a fixed position that does not scroll with the content. The following attributes can be used to position the fab with respect to the content:
-
-| Value        | Alignment  | Details                                                                   |
-|--------------|------------|---------------------------------------------------------------------------|
-| `top`        | vertical   | Places the container at the top of the content.                           |
-| `bottom`     | vertical   | Places the container at the bottom of the content.                        |
-| `middle`     | vertical   | Places the container in the middle vertically.                            |
-| `edge`       | vertical   | Used to place the container between the content and the header/footer.    |
-| `left`       | horizontal | Places the container on the left.                                         |
-| `right`      | horizontal | Places the container on the right.                                        |
-| `center`     | horizontal | Places the container in the center horizontally.                          |
-
-The fab should have one main fab button. Fabs can also contain fab lists which contain related buttons that show when the main fab button is clicked. The same fab container can contain several [fab list](../../fab-list/FabList) elements with different side values.
-
-```html
-<ion-content>
-  <!-- fab placed to the top right -->
-  <ion-fab top right slot="fixed">
-    <ion-fab-button>
-      <ion-icon name="add"></ion-icon>
-    </ion-fab-button>
-  </ion-fab>
-
-  <!-- fab placed to the bottom right -->
-  <ion-fab bottom right slot="fixed">
-    <ion-fab-button>
-      <ion-icon name="arrow-dropleft"></ion-icon>
-    </ion-fab-button>
-  </ion-fab>
-
-  <!-- fab placed to the top left -->
-  <ion-fab top left slot="fixed">
-    <ion-fab-button>
-      <ion-icon name="arrow-dropright"></ion-icon>
-    </ion-fab-button>
-  </ion-fab>
-
-  <!-- fab placed to the bottom left -->
-  <ion-fab bottom left slot="fixed">
-    <ion-fab-button>
-      <ion-icon name="arrow-dropup"></ion-icon>
-    </ion-fab-button>
-  </ion-fab>
-
-  <!-- fab placed to the left and middle -->
-  <ion-fab left middle slot="fixed">
-    <ion-fab-button>
-      <ion-icon name="share"></ion-icon>
-    </ion-fab-button>
-  </ion-fab>
-
-  <!-- fab placed to the right and middle -->
-  <ion-fab right middle slot="fixed">
-    <ion-fab-button>
-      <ion-icon name="add"></ion-icon>
-    </ion-fab-button>
-  </ion-fab>
-
-  <!-- fab placed to the top and right and on the top edge of the content overlapping header -->
-  <ion-fab top right edge slot="fixed">
-    <ion-fab-button>
-      <ion-icon name="person"></ion-icon>
-    </ion-fab-button>
-  </ion-fab>
-
-  <!-- fab placed to the bottom and left and on the bottom edge of the content overlapping footer with a list to the right -->
-  <ion-fab bottom left edge slot="fixed">
-    <ion-fab-button>
-      <ion-icon name="settings"></ion-icon>
-    </ion-fab-button>
-    <ion-fab-list side="end">
-      <ion-fab-button><ion-icon name="logo-vimeo"></ion-icon></ion-fab-button>
-    </ion-fab-list>
-  </ion-fab>
-
-  <!-- fab placed in the center of the content with a list on each side -->
-  <ion-fab center middle slot="fixed">
-    <ion-fab-button><ion-icon name="share"></ion-icon></ion-fab-button>
-    <ion-fab-list side="top">
-      <ion-fab-button><ion-icon name="logo-vimeo"></ion-icon></ion-fab-button>
-    </ion-fab-list>
-    <ion-fab-list side="bottom">
-      <ion-fab-button><ion-icon name="logo-facebook"></ion-icon></ion-fab-button>
-    </ion-fab-list>
-    <ion-fab-list side="start">
-      <ion-fab-button><ion-icon name="logo-googleplus"></ion-icon></ion-fab-button>
-    </ion-fab-list>
-    <ion-fab-list side="end">
-      <ion-fab-button><ion-icon name="logo-twitter"></ion-icon></ion-fab-button>
-    </ion-fab-list>
-  </ion-fab>
-</ion-content>
-```
-
+Fabs are container elements that contain one or more fab buttons. They should be placed in a fixed position that does not scroll with the content. Fab should have one main fab-button. Fabs can also contain fab-lists which contain related buttons that show when the main fab button is clicked. The same fab container can contain several [fab-list](../../fab-list/FabList) elements with different side values.
 
 <!-- Auto Generated Below -->
 
-
 ## Properties
 
 #### activated
 
 boolean
 
-
 #### edge
 
 boolean
@@ -113,7 +18,6 @@ If true, the fab will display on the edge of the header if
 `vertical` is `"top"`, and on the edge of the footer if
 it is `"bottom"`. Should be used with a `fixed` slot.
 
-
 #### horizontal
 
 string
@@ -121,7 +25,6 @@ string
 Where to align the fab horizontally in the viewport.
 Possible values are: `"center"`, `"start"`, `"end"`.
 
-
 #### vertical
 
 string
@@ -129,14 +32,12 @@ string
 Where to align the fab vertically in the viewport.
 Possible values are: `"top"`, `"center"`, `"bottom"`.
 
-
 ## Attributes
 
 #### activated
 
 boolean
 
-
 #### edge
 
 boolean
@@ -145,7 +46,6 @@ If true, the fab will display on the edge of the header if
 `vertical` is `"top"`, and on the edge of the footer if
 it is `"bottom"`. Should be used with a `fixed` slot.
 
-
 #### horizontal
 
 string
@@ -153,7 +53,6 @@ string
 Where to align the fab horizontally in the viewport.
 Possible values are: `"center"`, `"start"`, `"end"`.
 
-
 #### vertical
 
 string
@@ -161,15 +60,12 @@ string
 Where to align the fab vertically in the viewport.
 Possible values are: `"top"`, `"center"`, `"bottom"`.
 
-
 ## Methods
 
 #### close()
 
 Close an active FAB list container
 
+---
 
-
-----------------------------------------------
-
-*Built with [StencilJS](https://stenciljs.com/)*
+_Built with [StencilJS](https://stenciljs.com/)_
diff --git a/core/src/components/fab/usage/javascript.md b/core/src/components/fab/usage/javascript.md
new file mode 100644
index 0000000000..3645f979ea
--- /dev/null
+++ b/core/src/components/fab/usage/javascript.md
@@ -0,0 +1,81 @@
+```html
+<ion-content>
+  <!-- fab placed to the top end -->
+  <ion-fab vertical="top" horizontal="end" slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="add"></ion-icon>
+    </ion-fab-button>
+  </ion-fab>
+
+  <!-- fab placed to the bottom end -->
+  <ion-fab vertical="bottom" horizontal="end" slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="arrow-dropleft"></ion-icon>
+    </ion-fab-button>
+  </ion-fab>
+
+  <!-- fab placed to the top start -->
+  <ion-fab vertical="top" horizontal="start" slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="arrow-dropright"></ion-icon>
+    </ion-fab-button>
+  </ion-fab>
+
+  <!-- fab placed to the bottom start -->
+  <ion-fab vertical="bottom" horizontal="start" slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="arrow-dropup"></ion-icon>
+    </ion-fab-button>
+  </ion-fab>
+
+  <!-- fab placed to the (vertical) center and start -->
+  <ion-fab vertical="center" horizontal="start" slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="share"></ion-icon>
+    </ion-fab-button>
+  </ion-fab>
+
+  <!-- fab placed to the (vertical) center and end -->
+  <ion-fab vertical="center" horizontal="end" slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="add"></ion-icon>
+    </ion-fab-button>
+  </ion-fab>
+
+  <!-- fab placed to the top and end and on the top edge of the content overlapping header -->
+  <ion-fab vertical="top" horizontal="end" edge slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="person"></ion-icon>
+    </ion-fab-button>
+  </ion-fab>
+
+  <!-- fab placed to the bottom and start and on the bottom edge of the content overlapping footer with a list to the right -->
+  <ion-fab vertical="bottom" horizontal="start" edge slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="settings"></ion-icon>
+    </ion-fab-button>
+    <ion-fab-list side="end">
+      <ion-fab-button><ion-icon name="logo-vimeo"></ion-icon></ion-fab-button>
+    </ion-fab-list>
+  </ion-fab>
+
+  <!-- fab placed in the center of the content with a list on each side -->
+  <ion-fab vertical="center" horizontal="center" slot="fixed">
+    <ion-fab-button>
+      <ion-icon name="share"></ion-icon>
+    </ion-fab-button>
+    <ion-fab-list side="top">
+      <ion-fab-button><ion-icon name="logo-vimeo"></ion-icon></ion-fab-button>
+    </ion-fab-list>
+    <ion-fab-list side="bottom">
+      <ion-fab-button><ion-icon name="logo-facebook"></ion-icon></ion-fab-button>
+    </ion-fab-list>
+    <ion-fab-list side="start">
+      <ion-fab-button><ion-icon name="logo-googleplus"></ion-icon></ion-fab-button>
+    </ion-fab-list>
+    <ion-fab-list side="end">
+      <ion-fab-button><ion-icon name="logo-twitter"></ion-icon></ion-fab-button>
+    </ion-fab-list>
+  </ion-fab>
+</ion-content>
+```