From 8ee7b91f22b4556c71c1d0e9d53643d5534c1bac Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Thu, 22 Dec 2016 23:04:02 -0800
Subject: [PATCH 01/29] unify alignment of all these dang navbar forms

---
 docs/components/navbar.md                     | 36 +++++++++----------
 docs/examples/carousel/index.html             |  6 ++--
 docs/examples/dashboard/index.html            |  4 +--
 docs/examples/navbar-top-fixed/index.html     |  6 ++--
 docs/examples/navbar-top/index.html           |  6 ++--
 docs/examples/navbars/index.html              | 12 +++----
 docs/examples/sticky-footer-navbar/index.html |  6 ++--
 7 files changed, 38 insertions(+), 38 deletions(-)

diff --git a/docs/components/navbar.md b/docs/components/navbar.md
index 2555a78d3dfe..5fa6a1fd5ce7 100644
--- a/docs/components/navbar.md
+++ b/docs/components/navbar.md
@@ -58,8 +58,8 @@ Here's an example of all the sub-components included in a responsive light-theme
       </li>
     </ul>
     <form class="form-inline mt-2 mt-md-0">
-      <input class="form-control mr-md-2" type="text" placeholder="Search">
-      <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+      <input class="form-control mr-sm-2" type="text" placeholder="Search">
+      <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
     </form>
   </div>
 </nav>
@@ -193,8 +193,8 @@ Place various form controls and components within a navbar with `.form-inline`.
 {% example html %}
 <nav class="navbar navbar-light bg-faded">
   <form class="form-inline">
-    <input class="form-control mr-md-2" type="text" placeholder="Search">
-    <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+    <input class="form-control mr-sm-2" type="text" placeholder="Search">
+    <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
   </form>
 </nav>
 {% endexample %}
@@ -204,8 +204,8 @@ Align the contents of your inline forms with utilities as needed.
 {% example html %}
 <nav class="navbar navbar-light bg-faded flex-items-right">
   <form class="form-inline">
-    <input class="form-control mr-md-2" type="text" placeholder="Search">
-    <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+    <input class="form-control mr-sm-2" type="text" placeholder="Search">
+    <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
   </form>
 </nav>
 {% endexample %}
@@ -300,8 +300,8 @@ Theming the navbar has never been easier thanks to the combination of theming cl
         </li>
       </ul>
       <form class="form-inline">
-        <input class="form-control mr-md-2" type="text" placeholder="Search">
-        <button class="btn btn-outline-info my-2 my-lg-0" type="submit">Search</button>
+        <input class="form-control mr-sm-2" type="text" placeholder="Search">
+        <button class="btn btn-outline-info my-2 my-sm-0" type="submit">Search</button>
       </form>
     </div>
   </nav>
@@ -328,8 +328,8 @@ Theming the navbar has never been easier thanks to the combination of theming cl
         </li>
       </ul>
       <form class="form-inline">
-        <input class="form-control mr-md-2" type="text" placeholder="Search">
-        <button class="btn btn-outline-secondary my-2 my-lg-0" type="submit">Search</button>
+        <input class="form-control mr-sm-2" type="text" placeholder="Search">
+        <button class="btn btn-outline-secondary my-2 my-sm-0" type="submit">Search</button>
       </form>
     </div>
   </nav>
@@ -356,8 +356,8 @@ Theming the navbar has never been easier thanks to the combination of theming cl
         </li>
       </ul>
       <form class="form-inline">
-        <input class="form-control mr-md-2" type="text" placeholder="Search">
-        <button class="btn btn-outline-primary my-2 my-lg-0" type="submit">Search</button>
+        <input class="form-control mr-sm-2" type="text" placeholder="Search">
+        <button class="btn btn-outline-primary my-2 my-sm-0" type="submit">Search</button>
       </form>
     </div>
   </nav>
@@ -449,9 +449,9 @@ With no `.navbar-brand` shown in lowest breakpoint:
         <a class="nav-link disabled" href="#">Disabled</a>
       </li>
     </ul>
-    <form class="form-inline mt-2 mt-lg-0">
-      <input class="form-control mr-md-2" type="text" placeholder="Search">
-      <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+    <form class="form-inline mt-2 mt-md-0">
+      <input class="form-control mr-sm-2" type="text" placeholder="Search">
+      <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
     </form>
   </div>
 </nav>
@@ -478,9 +478,9 @@ With a brand name shown on the left and toggler on the right:
         <a class="nav-link disabled" href="#">Disabled</a>
       </li>
     </ul>
-    <form class="form-inline mt-2 mt-lg-0">
-      <input class="form-control mr-md-2" type="text" placeholder="Search">
-      <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+    <form class="form-inline mt-2 mt-md-0">
+      <input class="form-control mr-sm-2" type="text" placeholder="Search">
+      <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
     </form>
   </div>
 </nav>
diff --git a/docs/examples/carousel/index.html b/docs/examples/carousel/index.html
index fa05558fd540..71f3c17f450d 100644
--- a/docs/examples/carousel/index.html
+++ b/docs/examples/carousel/index.html
@@ -36,9 +36,9 @@
             <a class="nav-link disabled" href="#">Disabled</a>
           </li>
         </ul>
-        <form class="form-inline mt-2 mt-lg-0">
-          <input class="form-control mr-md-2" type="text" placeholder="Search">
-          <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+        <form class="form-inline mt-2 mt-md-0">
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
         </form>
       </div>
     </nav>
diff --git a/docs/examples/dashboard/index.html b/docs/examples/dashboard/index.html
index 9b9155f20529..a1f34cb9406c 100644
--- a/docs/examples/dashboard/index.html
+++ b/docs/examples/dashboard/index.html
@@ -41,8 +41,8 @@
           </li>
         </ul>
         <form class="form-inline mt-2 mt-md-0">
-          <input class="form-control mr-md-2" type="text" placeholder="Search">
-          <button class="btn btn-outline-success my-2 my-md-0" type="submit">Search</button>
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
         </form>
       </div>
     </nav>
diff --git a/docs/examples/navbar-top-fixed/index.html b/docs/examples/navbar-top-fixed/index.html
index 0bf1c9a05d13..1ec4bf6a9537 100644
--- a/docs/examples/navbar-top-fixed/index.html
+++ b/docs/examples/navbar-top-fixed/index.html
@@ -37,9 +37,9 @@
             <a class="nav-link disabled" href="#">Disabled</a>
           </li>
         </ul>
-        <form class="form-inline mt-2 mt-lg-0">
-          <input class="form-control mr-md-2" type="text" placeholder="Search">
-          <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+        <form class="form-inline mt-2 mt-md-0">
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
         </form>
       </div>
     </nav>
diff --git a/docs/examples/navbar-top/index.html b/docs/examples/navbar-top/index.html
index dde2cb7f1a45..e000fa256846 100644
--- a/docs/examples/navbar-top/index.html
+++ b/docs/examples/navbar-top/index.html
@@ -37,9 +37,9 @@
             <a class="nav-link disabled" href="#">Disabled</a>
           </li>
         </ul>
-        <form class="form-inline mt-2 mt-lg-0">
-          <input class="form-control mr-md-2" type="text" placeholder="Search">
-          <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+        <form class="form-inline mt-2 mt-md-0">
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
         </form>
       </div>
     </nav>
diff --git a/docs/examples/navbars/index.html b/docs/examples/navbars/index.html
index 6ad1b49c5c3a..7b624fbe5ea3 100644
--- a/docs/examples/navbars/index.html
+++ b/docs/examples/navbars/index.html
@@ -47,8 +47,8 @@
           </li>
         </ul>
         <form class="form-inline mt-2 mt-md-0">
-          <input class="form-control mr-md-2" type="text" placeholder="Search">
-          <button class="btn btn-outline-success my-2 my-md-0" type="submit">Search</button>
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
         </form>
       </div>
     </nav>
@@ -81,8 +81,8 @@
             </li>
           </ul>
           <form class="form-inline mt-2 mt-md-0">
-            <input class="form-control mr-md-2" type="text" placeholder="Search">
-            <button class="btn btn-outline-success my-2 my-md-0" type="submit">Search</button>
+            <input class="form-control mr-sm-2" type="text" placeholder="Search">
+            <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
           </form>
         </div>
       </div>
@@ -144,8 +144,8 @@
             </li>
           </ul>
           <form class="form-inline mt-2 mt-md-0">
-            <input class="form-control mr-md-2" type="text" placeholder="Search">
-            <button class="btn btn-outline-success my-2 my-md-0" type="submit">Search</button>
+            <input class="form-control mr-sm-2" type="text" placeholder="Search">
+            <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
           </form>
         </div>
       </nav>
diff --git a/docs/examples/sticky-footer-navbar/index.html b/docs/examples/sticky-footer-navbar/index.html
index de8df792deff..e972de7f5d3b 100644
--- a/docs/examples/sticky-footer-navbar/index.html
+++ b/docs/examples/sticky-footer-navbar/index.html
@@ -38,9 +38,9 @@
             <a class="nav-link disabled" href="#">Disabled</a>
           </li>
         </ul>
-        <form class="form-inline mt-2 mt-lg-0">
-          <input class="form-control mr-md-2" type="text" placeholder="Search">
-          <button class="btn btn-outline-success my-2 my-lg-0" type="submit">Search</button>
+        <form class="form-inline mt-2 mt-md-0">
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
         </form>
       </div>
     </nav>

From 7ee586b8b00403883e08c9b1cd4bab8d72a62f76 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Thu, 22 Dec 2016 23:05:31 -0800
Subject: [PATCH 02/29] better/more form spacing in navbars

---
 docs/components/navbar.md        | 6 +++---
 docs/examples/navbars/index.html | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/components/navbar.md b/docs/components/navbar.md
index 5fa6a1fd5ce7..57e0bad7a185 100644
--- a/docs/components/navbar.md
+++ b/docs/components/navbar.md
@@ -57,7 +57,7 @@ Here's an example of all the sub-components included in a responsive light-theme
         <a class="nav-link disabled" href="#">Disabled</a>
       </li>
     </ul>
-    <form class="form-inline mt-2 mt-md-0">
+    <form class="form-inline my-2 my-lg-0">
       <input class="form-control mr-sm-2" type="text" placeholder="Search">
       <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
     </form>
@@ -449,7 +449,7 @@ With no `.navbar-brand` shown in lowest breakpoint:
         <a class="nav-link disabled" href="#">Disabled</a>
       </li>
     </ul>
-    <form class="form-inline mt-2 mt-md-0">
+    <form class="form-inline my-2 my-lg-0">
       <input class="form-control mr-sm-2" type="text" placeholder="Search">
       <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
     </form>
@@ -478,7 +478,7 @@ With a brand name shown on the left and toggler on the right:
         <a class="nav-link disabled" href="#">Disabled</a>
       </li>
     </ul>
-    <form class="form-inline mt-2 mt-md-0">
+    <form class="form-inline my-2 my-lg-0">
       <input class="form-control mr-sm-2" type="text" placeholder="Search">
       <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
     </form>
diff --git a/docs/examples/navbars/index.html b/docs/examples/navbars/index.html
index 7b624fbe5ea3..f56a85d881df 100644
--- a/docs/examples/navbars/index.html
+++ b/docs/examples/navbars/index.html
@@ -46,7 +46,7 @@
             </div>
           </li>
         </ul>
-        <form class="form-inline mt-2 mt-md-0">
+        <form class="form-inline my-2 my-lg-0">
           <input class="form-control mr-sm-2" type="text" placeholder="Search">
           <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
         </form>
@@ -80,7 +80,7 @@
               </div>
             </li>
           </ul>
-          <form class="form-inline mt-2 mt-md-0">
+          <form class="form-inline my-2 my-lg-0">
             <input class="form-control mr-sm-2" type="text" placeholder="Search">
             <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
           </form>
@@ -143,7 +143,7 @@
               </div>
             </li>
           </ul>
-          <form class="form-inline mt-2 mt-md-0">
+          <form class="form-inline my-2 my-lg-0">
             <input class="form-control mr-sm-2" type="text" placeholder="Search">
             <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
           </form>

From 89a0cd0b6e858a0ebafa716c40edda12eccafd7b Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Thu, 22 Dec 2016 23:08:02 -0800
Subject: [PATCH 03/29] update navbars in jumbotron, offcanvas, starter
 examples to flex versions

---
 docs/examples/jumbotron/index.html        | 44 ++++++++++++++++-------
 docs/examples/offcanvas/index.html        | 39 +++++++++++++++-----
 docs/examples/starter-template/index.html | 44 ++++++++++++++++-------
 3 files changed, 93 insertions(+), 34 deletions(-)

diff --git a/docs/examples/jumbotron/index.html b/docs/examples/jumbotron/index.html
index f926b71f3af3..a062629a0b93 100644
--- a/docs/examples/jumbotron/index.html
+++ b/docs/examples/jumbotron/index.html
@@ -20,19 +20,37 @@
 
   <body>
 
-    <nav class="navbar navbar-fixed-top navbar-inverse bg-inverse">
-      <a class="navbar-brand" href="#">Project name</a>
-      <ul class="nav navbar-nav">
-        <li class="nav-item active">
-          <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link" href="#">About</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link" href="#">Contact</a>
-        </li>
-      </ul>
+    <nav class="navbar navbar-inverse navbar-fixed-top bg-inverse navbar-toggleable-md">
+      <button class="navbar-toggler navbar-toggler-right" type="button" data-toggle="collapse" data-target="#navbarsExampleDefault" aria-controls="navbarsExampleDefault" aria-expanded="false" aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+      </button>
+      <a class="navbar-brand" href="#">Navbar</a>
+
+      <div class="collapse navbar-collapse" id="navbarsExampleDefault">
+        <ul class="nav navbar-nav">
+          <li class="nav-item active">
+            <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
+          </li>
+          <li class="nav-item">
+            <a class="nav-link" href="#">Link</a>
+          </li>
+          <li class="nav-item">
+            <a class="nav-link disabled" href="#">Disabled</a>
+          </li>
+          <li class="nav-item dropdown">
+            <a class="nav-link dropdown-toggle" href="http://example.com" id="dropdown01" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown</a>
+            <div class="dropdown-menu" aria-labelledby="dropdown01">
+              <a class="dropdown-item" href="#">Action</a>
+              <a class="dropdown-item" href="#">Another action</a>
+              <a class="dropdown-item" href="#">Something else here</a>
+            </div>
+          </li>
+        </ul>
+        <form class="form-inline my-2 my-lg-0">
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
+        </form>
+      </div>
     </nav>
 
     <!-- Main jumbotron for a primary marketing message or call to action -->
diff --git a/docs/examples/offcanvas/index.html b/docs/examples/offcanvas/index.html
index 53f2db1602c9..8c86492713cb 100644
--- a/docs/examples/offcanvas/index.html
+++ b/docs/examples/offcanvas/index.html
@@ -19,16 +19,39 @@
   </head>
 
   <body>
-    <nav class="navbar navbar-fixed-top navbar-inverse bg-inverse">
-      <div class="container">
-        <a class="navbar-brand" href="#">Project name</a>
+
+    <nav class="navbar navbar-fixed-top navbar-inverse bg-inverse navbar-toggleable-md">
+      <button class="navbar-toggler navbar-toggler-right" type="button" data-toggle="collapse" data-target="#navbarsExampleDefault" aria-controls="navbarsExampleDefault" aria-expanded="false" aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+      </button>
+      <a class="navbar-brand" href="#">Navbar</a>
+
+      <div class="collapse navbar-collapse" id="navbarsExampleDefault">
         <ul class="nav navbar-nav">
-          <li class="nav-item active"><a class="nav-link" href="#">Home</a></li>
-          <li class="nav-item"><a class="nav-link" href="#about">About</a></li>
-          <li class="nav-item"><a class="nav-link" href="#contact">Contact</a></li>
+          <li class="nav-item active">
+            <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
+          </li>
+          <li class="nav-item">
+            <a class="nav-link" href="#">Link</a>
+          </li>
+          <li class="nav-item">
+            <a class="nav-link disabled" href="#">Disabled</a>
+          </li>
+          <li class="nav-item dropdown">
+            <a class="nav-link dropdown-toggle" href="http://example.com" id="dropdown01" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown</a>
+            <div class="dropdown-menu" aria-labelledby="dropdown01">
+              <a class="dropdown-item" href="#">Action</a>
+              <a class="dropdown-item" href="#">Another action</a>
+              <a class="dropdown-item" href="#">Something else here</a>
+            </div>
+          </li>
         </ul>
-      </div><!-- /.container -->
-    </nav><!-- /.navbar -->
+        <form class="form-inline my-2 my-lg-0">
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
+        </form>
+      </div>
+    </nav>
 
     <div class="container">
 
diff --git a/docs/examples/starter-template/index.html b/docs/examples/starter-template/index.html
index fe6dfc0691f5..b2f106b566c5 100644
--- a/docs/examples/starter-template/index.html
+++ b/docs/examples/starter-template/index.html
@@ -20,19 +20,37 @@
 
   <body>
 
-    <nav class="navbar navbar-fixed-top navbar-inverse bg-inverse">
-      <a class="navbar-brand" href="#">Project name</a>
-      <ul class="nav navbar-nav">
-        <li class="nav-item active">
-          <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link" href="#">About</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link" href="#">Contact</a>
-        </li>
-      </ul>
+    <nav class="navbar navbar-inverse bg-inverse navbar-fixed-top navbar-toggleable-md">
+      <button class="navbar-toggler navbar-toggler-right" type="button" data-toggle="collapse" data-target="#navbarsExampleDefault" aria-controls="navbarsExampleDefault" aria-expanded="false" aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+      </button>
+      <a class="navbar-brand" href="#">Navbar</a>
+
+      <div class="collapse navbar-collapse" id="navbarsExampleDefault">
+        <ul class="nav navbar-nav">
+          <li class="nav-item active">
+            <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
+          </li>
+          <li class="nav-item">
+            <a class="nav-link" href="#">Link</a>
+          </li>
+          <li class="nav-item">
+            <a class="nav-link disabled" href="#">Disabled</a>
+          </li>
+          <li class="nav-item dropdown">
+            <a class="nav-link dropdown-toggle" href="http://example.com" id="dropdown01" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown</a>
+            <div class="dropdown-menu" aria-labelledby="dropdown01">
+              <a class="dropdown-item" href="#">Action</a>
+              <a class="dropdown-item" href="#">Another action</a>
+              <a class="dropdown-item" href="#">Something else here</a>
+            </div>
+          </li>
+        </ul>
+        <form class="form-inline my-2 my-lg-0">
+          <input class="form-control mr-sm-2" type="text" placeholder="Search">
+          <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
+        </form>
+      </div>
     </nav>
 
     <div class="container">

From 8e455ff56105e210cd313786c23532b7b81d01c9 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Thu, 22 Dec 2016 23:19:21 -0800
Subject: [PATCH 04/29] Undo #21171 (which closed #20977)

Turns out we did have the correct height calculation with our custom selects. The problem was we lacked a shared line-height with our buttons and inputs.

This restores the previous `calc` math and adds a line-height that reuses the input line-height.
---
 scss/_custom-forms.scss | 3 ++-
 scss/_variables.scss    | 1 +
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/scss/_custom-forms.scss b/scss/_custom-forms.scss
index 1d74bc5f4105..0e9c76460db8 100644
--- a/scss/_custom-forms.scss
+++ b/scss/_custom-forms.scss
@@ -136,8 +136,9 @@
   display: inline-block;
   max-width: 100%;
   $select-border-width: ($border-width * 2);
-  height: calc(#{$input-height} - #{$select-border-width});
+  height: calc(#{$input-height} + #{$select-border-width});
   padding: $custom-select-padding-y ($custom-select-padding-x + $custom-select-indicator-padding) $custom-select-padding-y $custom-select-padding-x;
+  line-height: $custom-select-line-height;
   color: $custom-select-color;
   vertical-align: middle;
   background: $custom-select-bg $custom-select-indicator no-repeat right $custom-select-padding-x center;
diff --git a/scss/_variables.scss b/scss/_variables.scss
index a68e45d6e89f..412f944f530b 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -487,6 +487,7 @@ $custom-radio-checked-icon: str-replace(url("data:image/svg+xml;charset=utf8,%3C
 $custom-select-padding-x:          .75rem  !default;
 $custom-select-padding-y:          .375rem !default;
 $custom-select-indicator-padding:   1rem !default; // Extra padding to account for the presence of the background-image based indicator
+$custom-select-line-height:         $input-line-height !default;
 $custom-select-color:               $input-color !default;
 $custom-select-disabled-color:      $gray-light !default;
 $custom-select-bg:            $white !default;

From dcbe82b6cddc851b8be5f8af8aeae26cf097c9fa Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Thu, 22 Dec 2016 23:43:37 -0800
Subject: [PATCH 05/29] pull in changes from #19832 to fix offcanvas

---
 docs/examples/offcanvas/index.html    |  8 ++++----
 docs/examples/offcanvas/offcanvas.css | 10 ++++++++++
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/docs/examples/offcanvas/index.html b/docs/examples/offcanvas/index.html
index 8c86492713cb..7036277e26e7 100644
--- a/docs/examples/offcanvas/index.html
+++ b/docs/examples/offcanvas/index.html
@@ -57,8 +57,8 @@
 
       <div class="row row-offcanvas row-offcanvas-right">
 
-        <div class="col-12 col-sm-9">
-          <p class="float-right hidden-sm-up">
+        <div class="col-12 col-md-9">
+          <p class="float-right hidden-md-up">
             <button type="button" class="btn btn-primary btn-sm" data-toggle="offcanvas">Toggle nav</button>
           </p>
           <div class="jumbotron">
@@ -99,7 +99,7 @@ <h2>Heading</h2>
           </div><!--/row-->
         </div><!--/span-->
 
-        <div class="col-6 col-sm-3 sidebar-offcanvas" id="sidebar">
+        <div class="col-6 col-md-3 sidebar-offcanvas" id="sidebar">
           <div class="list-group">
             <a href="#" class="list-group-item active">Link</a>
             <a href="#" class="list-group-item">Link</a>
@@ -118,7 +118,7 @@ <h2>Heading</h2>
       <hr>
 
       <footer>
-        <p>&copy; Company 2014</p>
+        <p>&copy; Company 2017</p>
       </footer>
 
     </div><!--/.container-->
diff --git a/docs/examples/offcanvas/offcanvas.css b/docs/examples/offcanvas/offcanvas.css
index 2a72199d5938..6047cb304d9f 100644
--- a/docs/examples/offcanvas/offcanvas.css
+++ b/docs/examples/offcanvas/offcanvas.css
@@ -34,11 +34,21 @@ footer {
   }
 
   .row-offcanvas-right
+  .sidebar-offcanvas {
+    right: -100%; /* 12 columns */
+  }
+
+  .row-offcanvas-right.active
   .sidebar-offcanvas {
     right: -50%; /* 6 columns */
   }
 
   .row-offcanvas-left
+  .sidebar-offcanvas {
+    left: -100%; /* 12 columns */
+  }
+
+  .row-offcanvas-left.active
   .sidebar-offcanvas {
     left: -50%; /* 6 columns */
   }

From 0da87fef7cbea3c8217d27611c05b3d287dc6f7e Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 10:39:53 -0800
Subject: [PATCH 06/29] Make .nav flex-powered

- Set an explicit `display: flex` on the base `.nav` class and remove the floats/clearfixes from our navs.

- Set some global styles for `.nav-link`, a departure from the previous solution that featured no predefined padding.

- Move `.nav-link` from `inline-block` to `block` given this setting was added for our tabs and pills anyway.

- Remove horizontal margin from nav tabs; let folks set that on their own from now on.
---
 scss/_nav.scss | 39 +++------------------------------------
 1 file changed, 3 insertions(+), 36 deletions(-)

diff --git a/scss/_nav.scss b/scss/_nav.scss
index 10d5f5c6220c..66d16ef061c7 100644
--- a/scss/_nav.scss
+++ b/scss/_nav.scss
@@ -4,13 +4,15 @@
 // `<nav>`s or `<ul>`s.
 
 .nav {
+  display: flex;
   padding-left: 0;
   margin-bottom: 0;
   list-style: none;
 }
 
 .nav-link {
-  display: inline-block;
+  display: block;
+  padding: $nav-link-padding;
 
   @include hover-focus {
     text-decoration: none;
@@ -29,41 +31,18 @@
 }
 
 
-// Nav inline
-
-.nav-inline {
-  .nav-item {
-    display: inline-block;
-  }
-
-  .nav-item + .nav-item,
-  .nav-link + .nav-link {
-    margin-left: $nav-item-inline-spacer;
-  }
-}
-
-
 //
 // Tabs
 //
 
 .nav-tabs {
   border-bottom: $nav-tabs-border-width solid $nav-tabs-border-color;
-  @include clearfix();
 
   .nav-item {
-    float: left;
-    // Make the list-items overlay the bottom border
     margin-bottom: -$nav-tabs-border-width;
-
-    + .nav-item {
-      margin-left: $nav-item-margin;
-    }
   }
 
   .nav-link {
-    display: block;
-    padding: $nav-link-padding;
     border: $nav-tabs-border-width solid transparent;
     @include border-top-radius($nav-tabs-border-radius);
 
@@ -103,19 +82,7 @@
 //
 
 .nav-pills {
-  @include clearfix();
-
-  .nav-item {
-    float: left;
-
-    + .nav-item {
-      margin-left: $nav-item-margin;
-    }
-  }
-
   .nav-link {
-    display: block;
-    padding: $nav-link-padding;
     @include border-radius($nav-pills-border-radius);
   }
 

From 4e38337cbeea3a674772e107a8ac7e0ec011bd96 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 10:40:54 -0800
Subject: [PATCH 07/29] Change up the "justified" nav options

Given move to flexbox, we can make this available for everyone and clean it up some.

- Simplifies the `.nav-justified` styles to build on the flex-powered `.nav` base class.

- Adds the `.nav-fill` to make nav links fill available horizontal space, but not equal width.
---
 scss/_nav.scss | 44 +++++++++++++++-----------------------------
 1 file changed, 15 insertions(+), 29 deletions(-)

diff --git a/scss/_nav.scss b/scss/_nav.scss
index 66d16ef061c7..123d2b844bb6 100644
--- a/scss/_nav.scss
+++ b/scss/_nav.scss
@@ -96,24 +96,30 @@
   }
 }
 
-.nav-stacked {
+
+//
+// Justified variants
+//
+
+.nav-fill {
   .nav-item {
-    display: block;
-    float: none;
+    flex: 1 1 auto;
+    text-align: center;
+  }
+}
 
-    + .nav-item {
-      margin-top: $nav-item-margin;
-      margin-left: 0;
-    }
+.nav-justified {
+  .nav-item {
+    flex: 1 1 100%;
+    text-align: center;
   }
 }
 
 
-//
 // Tabbable tabs
 //
-
 // Hide tabbable panes to start, show them when `.active`
+
 .tab-content {
   > .tab-pane {
     display: none;
@@ -122,23 +128,3 @@
     display: block;
   }
 }
-
-
-// Justified navigation
-//
-// Justified nav components are only built for flexbox mode in Bootstrap 4. In
-// previous versions, this component variation was limited to anchor-based nav
-// implementations--meaning it couldn't be used on button elements. This is due
-// to a longstanding Safari bug in responsive table styles.
-//
-// Using flexbox, we avoid that problem altogether at the cost of no default
-// justified navigation for default Bootstrap. Sorry, y'all <3.
-
-.nav-justified {
-  display: flex;
-
-  .nav-item {
-    flex: 1;
-    text-align: center;
-  }
-}

From 9dff30b0a001352e20e894bbf5f823c9f5e213de Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 11:02:14 -0800
Subject: [PATCH 08/29] Revamp navs docs

- Reorganize things, leading with the base nav first instead of an accessibility note, and then moving the rest to a new available styles section.

- Add horizontal alignment options thanks to new flex utils (these new utils will be documented later in another commit).

- Dropped `.nav-stacked` for a flex util and added additional alignment options, so document those, too.
---
 docs/components/navs.md | 167 ++++++++++++++++++----------------------
 1 file changed, 75 insertions(+), 92 deletions(-)

diff --git a/docs/components/navs.md b/docs/components/navs.md
index 3b4b697a6a6a..fed519e8e579 100644
--- a/docs/components/navs.md
+++ b/docs/components/navs.md
@@ -12,15 +12,9 @@ Navigation available in Bootstrap share general markup and styles, from the base
 * Will be replaced with the ToC, excluding the "Contents" header
 {:toc}
 
-## Regarding accessibility
-
-If you are using navs to provide a navigation bar, be sure to add a `role="navigation"` to the most logical parent container of the `<ul>`, or wrap a `<nav>` element around the whole navigation. Do not add the role to the `<ul>` itself, as this would prevent it from being announced as an actual list by assistive technologies.
-
-## Examples
-
-### Base nav
+## Base nav
 
-Roll your own navigation style by extending the base `.nav` component. All Bootstrap's nav components are built on top of this by specifying additional styles. Includes styles for the disabled state, but **not the active state**.
+The base `.nav` component is built with flexbox and provide a strong foundation for building all types of navigation components. It includes some style overrides (for working with lists), some link padding for larger hit areas, and basic disabled styling. No active states are included in the base nav.
 
 {% example html %}
 <ul class="nav">
@@ -39,7 +33,7 @@ Roll your own navigation style by extending the base `.nav` component. All Boots
 </ul>
 {% endexample %}
 
-Classes are used throughout, so your markup can be super flexible. Use `<ul>`s like above, or roll your own with say a `<nav>` element. The change in nav item display below **is intentional** as `<li>`s have a different default `display` than regular `<a>` elements.
+Classes are used throughout, so your markup can be super flexible. Use `<ul>`s like above, or roll your own with say a `<nav>` element. Because the `.nav` uses `display: flex`, the nav links behave the same as nav items would, but without the extra markup.
 
 {% example html %}
 <nav class="nav">
@@ -50,44 +44,18 @@ Classes are used throughout, so your markup can be super flexible. Use `<ul>`s l
 </nav>
 {% endexample %}
 
-### Inline
-
-Space out nav links in a horizontal band with `.nav-inline`. Longer series of links will wrap to a new line.
-
-{% example html %}
-<nav class="nav nav-inline">
-  <a class="nav-link active" href="#">Active</a>
-  <a class="nav-link" href="#">Link</a>
-  <a class="nav-link" href="#">Link</a>
-  <a class="nav-link disabled" href="#">Disabled</a>
-</nav>
-{% endexample %}
+## Available styles
 
-The same works for a navigation built with lists.
+Change the style of `.nav`s component with modifiers and utilities. Mix and match as needed, or build your own.
 
-{% example html %}
-<ul class="nav nav-inline">
-  <li class="nav-item">
-    <a class="nav-link active" href="#">Active</a>
-  </li>
-  <li class="nav-item">
-    <a class="nav-link" href="#">Link</a>
-  </li>
-  <li class="nav-item">
-    <a class="nav-link" href="#">Link</a>
-  </li>
-  <li class="nav-item">
-    <a class="nav-link disabled" href="#">Disabled</a>
-  </li>
-</ul>
-{% endexample %}
+### Horizontal alignment
 
-### Tabs
+Change the horizontal alignment of your nav with [flexbox utilities]({{ site.baseurl }}/layout/grid/#horizontal-alignment). By default, navs are left-aligned, but you can easily change them to center or right aligned.
 
-Takes the basic nav from above and adds the `.nav-tabs` class to generate a tabbed interface. Use them to create tabbable regions with our [tab JavaScript plugin](#javascript-behavior).
+Centered with `.justify-content-center`:
 
 {% example html %}
-<ul class="nav nav-tabs">
+<ul class="nav justify-content-center">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
@@ -103,12 +71,10 @@ Takes the basic nav from above and adds the `.nav-tabs` class to generate a tabb
 </ul>
 {% endexample %}
 
-### Pills
-
-Take that same HTML, but use `.nav-pills` instead:
+Right-aligned with `.justify-content-end`:
 
 {% example html %}
-<ul class="nav nav-pills">
+<ul class="nav justify-content-end">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
@@ -124,12 +90,12 @@ Take that same HTML, but use `.nav-pills` instead:
 </ul>
 {% endexample %}
 
-### Stacked pills
+### Vertical
 
-Add `.nav-stacked` to the `.nav.nav-pills` to stack them vertically. Each `.nav-link` becomes block-level, allowing for larger hit areas via mouse or tap.
+Stack your navigation by changing the flex item direction with the `.flex-column` utility. Need to stack them on some viewports but not others? Use the responsive versions (e.g., `.flex-sm-column`).
 
 {% example html %}
-<ul class="nav nav-pills nav-stacked">
+<ul class="nav flex-column">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
@@ -145,10 +111,10 @@ Add `.nav-stacked` to the `.nav.nav-pills` to stack them vertically. Each `.nav-
 </ul>
 {% endexample %}
 
-As always, stacked pills are possible without `<ul>`s.
+As always, vertical navigation is possible without `<ul>`s, too.
 
 {% example html %}
-<nav class="nav nav-pills nav-stacked">
+<nav class="nav flex-column">
   <a class="nav-link active" href="#">Active</a>
   <a class="nav-link" href="#">Link</a>
   <a class="nav-link" href="#">Link</a>
@@ -156,26 +122,17 @@ As always, stacked pills are possible without `<ul>`s.
 </nav>
 {% endexample %}
 
-## Using dropdowns
-
-Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin]({{ site.baseurl }}/components/dropdowns/#usage).
+### Tabs
 
-### Tabs with dropdowns
+Takes the basic nav from above and adds the `.nav-tabs` class to generate a tabbed interface. Use them to create tabbable regions with our [tab JavaScript plugin](#javascript-behavior).
 
 {% example html %}
 <ul class="nav nav-tabs">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
-  <li class="nav-item dropdown">
-    <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">Dropdown</a>
-    <div class="dropdown-menu">
-      <a class="dropdown-item" href="#">Action</a>
-      <a class="dropdown-item" href="#">Another action</a>
-      <a class="dropdown-item" href="#">Something else here</a>
-      <div class="dropdown-divider"></div>
-      <a class="dropdown-item" href="#">Separated link</a>
-    </div>
+  <li class="nav-item">
+    <a class="nav-link" href="#">Link</a>
   </li>
   <li class="nav-item">
     <a class="nav-link" href="#">Link</a>
@@ -186,22 +143,17 @@ Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin
 </ul>
 {% endexample %}
 
-### Pills with dropdowns
+### Pills
+
+Take that same HTML, but use `.nav-pills` instead:
 
 {% example html %}
 <ul class="nav nav-pills">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
-  <li class="nav-item dropdown">
-    <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">Dropdown</a>
-    <div class="dropdown-menu">
-      <a class="dropdown-item" href="#">Action</a>
-      <a class="dropdown-item" href="#">Another action</a>
-      <a class="dropdown-item" href="#">Something else here</a>
-      <div class="dropdown-divider"></div>
-      <a class="dropdown-item" href="#">Separated link</a>
-    </div>
+  <li class="nav-item">
+    <a class="nav-link" href="#">Link</a>
   </li>
   <li class="nav-item">
     <a class="nav-link" href="#">Link</a>
@@ -212,19 +164,17 @@ Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin
 </ul>
 {% endexample %}
 
-## Justified nav
+### Fill and justify
 
-Create equal-width links in a navigation component by adding `.nav-justified` to a `.nav` component. This works with the inline, tab, and pill variants.
-
-Using the inline nav:
+Force your `.nav`'s contents to extend the full available width one of two modifier classes. To proportionately fill all available space with your `.nav-item`s, use `.nav-fill`. Notice that all horizontal space is occupied, but not every nav item has the same width.
 
 {% example html %}
-<ul class="nav nav-inline nav-justified">
+<ul class="nav nav-pills nav-fill">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
   <li class="nav-item">
-    <a class="nav-link" href="#">Link</a>
+    <a class="nav-link" href="#">Longer nav link</a>
   </li>
   <li class="nav-item">
     <a class="nav-link" href="#">Link</a>
@@ -235,15 +185,15 @@ Using the inline nav:
 </ul>
 {% endexample %}
 
-You can also use it on tabs:
+For equal-width elements, use `.nav-justified`. All horizontal space will be occupied by nav links, but unlike the `.nav-fill` above, every nav item will be the same width.
 
 {% example html %}
-<ul class="nav nav-tabs nav-justified">
+<ul class="nav nav-pills nav-justified">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
   <li class="nav-item">
-    <a class="nav-link" href="#">Link</a>
+    <a class="nav-link" href="#">Longer nav link</a>
   </li>
   <li class="nav-item">
     <a class="nav-link" href="#">Link</a>
@@ -254,15 +204,43 @@ You can also use it on tabs:
 </ul>
 {% endexample %}
 
-And pills, too:
+## Working with flex utilities
+
+If you need responsive nav variations, consider using a series of [flex utilities](). While more verbose, these utilities offer greater customization across responsive breakpoints. In the example below, our nav will be stacked on the lowest breakpoint, then adapt to a horizontal layout that fills the available width starting from the small breakpoint.
 
 {% example html %}
-<ul class="nav nav-pills nav-justified">
+<nav class="nav nav-pills flex-column flex-sm-row">
+  <a class="flex-sm-fill text-sm-center nav-link active" href="#">Active</a>
+  <a class="flex-sm-fill text-sm-center nav-link" href="#">Link</a>
+  <a class="flex-sm-fill text-sm-center nav-link" href="#">Link</a>
+  <a class="flex-sm-fill text-sm-center nav-link disabled" href="#">Disabled</a>
+</nav>
+{% endexample %}
+
+## Regarding accessibility
+
+If you're using navs to provide a navigation bar, be sure to add a `role="navigation"` to the most logical parent container of the `<ul>`, or wrap a `<nav>` element around the whole navigation. Do not add the role to the `<ul>` itself, as this would prevent it from being announced as an actual list by assistive technologies.
+
+## Using dropdowns
+
+Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin]({{ site.baseurl }}/components/dropdowns/#usage).
+
+### Tabs with dropdowns
+
+{% example html %}
+<ul class="nav nav-tabs">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
-  <li class="nav-item">
-    <a class="nav-link" href="#">Link</a>
+  <li class="nav-item dropdown">
+    <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">Dropdown</a>
+    <div class="dropdown-menu">
+      <a class="dropdown-item" href="#">Action</a>
+      <a class="dropdown-item" href="#">Another action</a>
+      <a class="dropdown-item" href="#">Something else here</a>
+      <div class="dropdown-divider"></div>
+      <a class="dropdown-item" href="#">Separated link</a>
+    </div>
   </li>
   <li class="nav-item">
     <a class="nav-link" href="#">Link</a>
@@ -273,17 +251,22 @@ And pills, too:
 </ul>
 {% endexample %}
 
-## Centered nav
-
-Using our [flexbox utilities]({{ site.baseurl }}/layout/grid/#horizontal-alignment), you can also customize your navigation components to change the alignment of nav items. For example, here are center aligned links on the inline nav component.
+### Pills with dropdowns
 
 {% example html %}
-<ul class="nav nav-inline d-flex flex-items-center">
+<ul class="nav nav-pills">
   <li class="nav-item">
     <a class="nav-link active" href="#">Active</a>
   </li>
-  <li class="nav-item">
-    <a class="nav-link" href="#">Link</a>
+  <li class="nav-item dropdown">
+    <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">Dropdown</a>
+    <div class="dropdown-menu">
+      <a class="dropdown-item" href="#">Action</a>
+      <a class="dropdown-item" href="#">Another action</a>
+      <a class="dropdown-item" href="#">Something else here</a>
+      <div class="dropdown-divider"></div>
+      <a class="dropdown-item" href="#">Separated link</a>
+    </div>
   </li>
   <li class="nav-item">
     <a class="nav-link" href="#">Link</a>

From 123e0886cf5f216e67dee38e902ac1830605893e Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 11:23:22 -0800
Subject: [PATCH 09/29] fix incorrect class name for inline-flex

---
 scss/utilities/_display.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scss/utilities/_display.scss b/scss/utilities/_display.scss
index 6d38760e645d..b2fc976c1cda 100644
--- a/scss/utilities/_display.scss
+++ b/scss/utilities/_display.scss
@@ -14,6 +14,6 @@
     .d#{$infix}-table        { display: table !important; }
     .d#{$infix}-table-cell   { display: table-cell !important; }
     .d#{$infix}-flex         { display: flex !important; }
-    .d#{$infix}-flex-inline  { display: inline-flex !important; }
+    .d#{$infix}-inline-flex  { display: inline-flex !important; }
   }
 }

From a1f0fa15dbbe1d240561c01ae43bb39c8c8afefa Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 11:48:03 -0800
Subject: [PATCH 10/29] Start to blow out and document more flexbox utilities

- Adds new flexbox.md file to utilities docs

- Adds a `breakpoints.yml` data file for easier output of responsive classes in the docs. Will put this to use on other pages soon.

- Adds hella flex utils. There are some dupes for now, but they'll get removed in time.
---
 docs/_data/breakpoints.yml |  29 ++++++
 docs/_data/nav.yml         |   1 +
 docs/utilities/flexbox.md  | 196 +++++++++++++++++++++++++++++++++++++
 scss/utilities/_flex.scss  |  42 ++++++++
 4 files changed, 268 insertions(+)
 create mode 100644 docs/_data/breakpoints.yml
 create mode 100644 docs/utilities/flexbox.md

diff --git a/docs/_data/breakpoints.yml b/docs/_data/breakpoints.yml
new file mode 100644
index 000000000000..3c8cfe293c09
--- /dev/null
+++ b/docs/_data/breakpoints.yml
@@ -0,0 +1,29 @@
+- breakpoint: xs
+  abbr: ""
+  name: Extra small
+  min-width: 0px
+  container: ""
+
+- breakpoint: sm
+  abbr: -sm
+  name: Small
+  min-width: 576px
+  container: 540px
+
+- breakpoint: md
+  abbr: -md
+  name: Medium
+  min-width: 768px
+  container: 720px
+
+- breakpoint: lg
+  abbr: -lg
+  name: Large
+  min-width: 992px
+  container: 960px
+
+- breakpoint: xl
+  abbr: -xl
+  name: Extra large
+  min-width: 1200px
+  container: 1140px
diff --git a/docs/_data/nav.yml b/docs/_data/nav.yml
index 6723352f40f4..256e1bb9d7f0 100644
--- a/docs/_data/nav.yml
+++ b/docs/_data/nav.yml
@@ -56,6 +56,7 @@
     - title: Clearfix
     - title: Close icon
     - title: Colors
+    - title: Flexbox
     - title: Display property
     - title: Image replacement
     - title: Invisible content
diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
new file mode 100644
index 000000000000..324bfa2f0533
--- /dev/null
+++ b/docs/utilities/flexbox.md
@@ -0,0 +1,196 @@
+---
+layout: docs
+title: Flexbox
+group: utilities
+---
+
+Quickly manage the layout, alignment, and sizing of grid columns, navigation, components, and more with a full suite of responsive flexbox utilities. For more complex implementations, custom CSS may be necessary.
+
+## Contents
+
+* Will be replaced with the ToC, excluding the "Contents" header
+{:toc}
+
+## Enable flex behaviors
+
+Apply `display` utilities to create a flexbox container and transform **direct children elements** into flex items. Flex containers and items are able to be modified further with additional flex properties. Choose from the following options.
+
+| Class | property: value; | Description |
+| --- | --- | --- |
+| `.d-flex` | `display: flex;` | Creates a block-level element using the flexbox model. |
+| `.d-inline-flex` | `display: inline-flex;` | Creates an inline-level element using the flexbox model. |
+
+{% example html %}
+<div class="d-flex p-2 bd-highlight">I'm a flexbox container!</div>
+{% endexample %}
+
+{% example html %}
+<div class="d-inline-flex p-2 bd-highlight">I'm an inline flexbox container!</div>
+{% endexample %}
+
+Responsive variations also exist for `.d-flex` and `.d-inline-flex`.
+
+<table class="table-responsive">
+  <thead>
+    <tr class="bg-faded">
+      <th>Class</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    {% for bp in site.data.breakpoints %}
+    <tr>
+      <td>
+        <code>.d{{ bp.abbr }}-flex</code>
+      </td>
+      <td>
+        Sets <code>display: flex;</code> on viewports {{ bp.min-width }} wide and up
+      </td>
+    </tr>
+    {% endfor %}
+    {% for bp in site.data.breakpoints %}
+    <tr>
+      <td>
+        <code>.d{{ bp.abbr }}-inline-flex</code>
+      </td>
+      <td>
+        Sets <code>display: inline-flex;</code> on viewports {{ bp.min-width }} wide and up
+      </td>
+    </tr>
+    {% endfor %}
+  </tbody>
+</table>
+
+## Direction
+
+Set the direction of flex items in a flex container with direction utilities. In most cases you can omit the horizontal class here as the browser default is `row`. However, you may encounter situations where you needed to explicitly set this value (like responsive layouts).
+
+Use `.flex-row` to set a horizontal direction.
+
+{% example html %}
+<div class="d-flex flex-row bd-highlight">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+{% endexample %}
+
+Use `.flex-column` to set a vertical direction.
+
+{% example html %}
+<div class="d-flex flex-column bd-highlight">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+{% endexample %}
+
+Responsive variations also exist for `.flex-row` and `.flex-column`.
+
+<table class="table-responsive">
+  <thead>
+    <tr class="bg-faded">
+      <th>Class</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    {% for bp in site.data.breakpoints %}
+    <tr>
+      <td>
+        <code>.flex{{ bp.abbr }}-row</code>
+      </td>
+      <td>
+        Sets <code>flex-direction: row;</code> on viewports {{ bp.min-width }} wide and up
+      </td>
+    </tr>
+    {% endfor %}
+    {% for bp in site.data.breakpoints %}
+    <tr>
+      <td>
+        <code>.flex{{ bp.abbr }}-column</code>
+      </td>
+      <td>
+        Sets <code>flex-direction: column;</code> on viewports {{ bp.min-width }} wide and up
+      </td>
+    </tr>
+    {% endfor %}
+  </tbody>
+</table>
+
+## Wrap
+
+Change how flex items wrap in a flex container. Choose from no wrapping at all (the browser default) with `.flex-nowrap`, or enable wrapping with `.flex-wrap`.
+
+{% example html %}
+<div class="d-flex flex-nowrap bd-highlight">
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+<div class="p-2 bd-highlight">Flex item</div>
+</div>
+{% endexample %}
+
+{% example html %}
+<div class="d-flex flex-wrap bd-highlight">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+{% endexample %}
+
+Responsive variations also exist for `.flex-nowrap` and `.flex-wrap`.
+
+<table class="table-responsive">
+  <thead>
+    <tr class="bg-faded">
+      <th>Class</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    {% for bp in site.data.breakpoints %}
+    <tr>
+      <td>
+        <code>.flex{{ bp.abbr }}-nowrap</code>
+      </td>
+      <td>
+        Sets <code>flex-wrap: nowrap;</code> on viewports {{ bp.min-width }} wide and up
+      </td>
+    </tr>
+    {% endfor %}
+    {% for bp in site.data.breakpoints %}
+    <tr>
+      <td>
+        <code>.flex{{ bp.abbr }}-wrap</code>
+      </td>
+      <td>
+        Sets <code>flex-wrap: wrap;</code> on viewports {{ bp.min-width }} wide and up
+      </td>
+    </tr>
+    {% endfor %}
+  </tbody>
+</table>
diff --git a/scss/utilities/_flex.scss b/scss/utilities/_flex.scss
index 4d13e9f8c542..c9783c2c8a86 100644
--- a/scss/utilities/_flex.scss
+++ b/scss/utilities/_flex.scss
@@ -27,5 +27,47 @@
     .flex-items#{$infix}-right   { justify-content: flex-end; }
     .flex-items#{$infix}-around  { justify-content: space-around; }
     .flex-items#{$infix}-between { justify-content: space-between; }
+
+    //
+    // New flex utils to replace and extend the ones above
+    //
+
+    .flex#{$infix}-fill { flex: 1 1 auto; }
+    .flex#{$infix}-justify { flex: 1 1 100%; }
+
+    .flex#{$infix}-row      { flex-direction: row !important; }
+    .flex#{$infix}-column   { flex-direction: column !important; }
+
+    .flex#{$infix}-wrap     { flex-wrap: wrap !important; }
+    .flex#{$infix}-nowrap   { flex-wrap: nowrap !important; }
+
+    .justify-content#{$infix}-start    { justify-content: flex-start !important; }
+    .justify-content#{$infix}-end      { justify-content: flex-end !important; }
+    .justify-content#{$infix}-center   { justify-content: center !important; }
+    .justify-content#{$infix}-between  { justify-content: space-between !important; }
+    .justify-content#{$infix}-around   { justify-content: space-around !important; }
+
+    .align-items#{$infix}-start      { align-items: flex-start !important; }
+    .align-items#{$infix}-end        { align-items: flex-end !important; }
+    .align-items#{$infix}-center     { align-items: center !important; }
+    .align-items#{$infix}-baseline   { align-items: baseline !important; }
+    .align-items#{$infix}-stretch    { align-items: stretch !important; }
+
+    .align-content#{$infix}-start    { align-content: flex-start !important; }
+    .align-content#{$infix}-end      { align-content: flex-end !important; }
+    .align-content#{$infix}-center   { align-content: center !important; }
+    .align-content#{$infix}-between  { align-content: space-between !important; }
+    .align-content#{$infix}-around   { align-content: space-around !important; }
+    .align-content#{$infix}-stretch  { align-content: stretch !important; }
+
+    // Item
+    .flex#{$infix}-auto { flex: 1 1 auto !important; }
+
+    .align-self#{$infix}-auto        { align-self: auto !important; }
+    .align-self#{$infix}-start       { align-self: flex-start !important; }
+    .align-self#{$infix}-end         { align-self: flex-end !important; }
+    .align-self#{$infix}-center      { align-self: center !important; }
+    .align-self#{$infix}-baseline    { align-self: baseline !important; }
+    .align-self#{$infix}-stretch     { align-self: stretch !important; }
   }
 }

From 2e9c4f0b54b1514e6c14bb2fbb908d65a3c5ef67 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 11:48:38 -0800
Subject: [PATCH 11/29] add docs class for highlighting

---
 docs/assets/scss/_component-examples.scss | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/assets/scss/_component-examples.scss b/docs/assets/scss/_component-examples.scss
index ece2db8dade5..c13218f0f1d2 100644
--- a/docs/assets/scss/_component-examples.scss
+++ b/docs/assets/scss/_component-examples.scss
@@ -43,6 +43,11 @@
   background-color: rgba(255,0,0,.1);
 }
 
+.bd-highlight {
+  background-color: rgba($bd-purple, .15);
+  border: 1px solid rgba($bd-purple, .15);
+}
+
 
 //
 // Container illustrations

From f4884f9fddfc8130d7a58f1c2ec225d80179b8e1 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 11:56:07 -0800
Subject: [PATCH 12/29] try out alt responsive variation lists

---
 docs/utilities/flexbox.md | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index 324bfa2f0533..a05c117e7f9f 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -13,12 +13,7 @@ Quickly manage the layout, alignment, and sizing of grid columns, navigation, co
 
 ## Enable flex behaviors
 
-Apply `display` utilities to create a flexbox container and transform **direct children elements** into flex items. Flex containers and items are able to be modified further with additional flex properties. Choose from the following options.
-
-| Class | property: value; | Description |
-| --- | --- | --- |
-| `.d-flex` | `display: flex;` | Creates a block-level element using the flexbox model. |
-| `.d-inline-flex` | `display: inline-flex;` | Creates an inline-level element using the flexbox model. |
+Apply `display` utilities to create a flexbox container and transform **direct children elements** into flex items. Flex containers and items are able to be modified further with additional flex properties.
 
 {% example html %}
 <div class="d-flex p-2 bd-highlight">I'm a flexbox container!</div>
@@ -30,7 +25,11 @@ Apply `display` utilities to create a flexbox container and transform **direct c
 
 Responsive variations also exist for `.d-flex` and `.d-inline-flex`.
 
-<table class="table-responsive">
+{% for bp in site.data.breakpoints %}
+- `.d{{ bp.abbr }}-flex`
+- `.d{{ bp.abbr }}-inline-flex`{% endfor %}
+
+<table class="table-responsive" hidden>
   <thead>
     <tr class="bg-faded">
       <th>Class</th>
@@ -87,7 +86,11 @@ Use `.flex-column` to set a vertical direction.
 
 Responsive variations also exist for `.flex-row` and `.flex-column`.
 
-<table class="table-responsive">
+{% for bp in site.data.breakpoints %}
+- `.flex{{ bp.abbr }}-row`
+- `.flex{{ bp.abbr }}-column`{% endfor %}
+
+<table class="table-responsive" hidden>
   <thead>
     <tr class="bg-faded">
       <th>Class</th>
@@ -164,7 +167,11 @@ Change how flex items wrap in a flex container. Choose from no wrapping at all (
 
 Responsive variations also exist for `.flex-nowrap` and `.flex-wrap`.
 
-<table class="table-responsive">
+{% for bp in site.data.breakpoints %}
+- `.flex{{ bp.abbr }}-nowrap`
+- `.flex{{ bp.abbr }}-wrap`{% endfor %}
+
+<table class="table-responsive" hidden>
   <thead>
     <tr class="bg-faded">
       <th>Class</th>

From 9c5c25816a64b8553b80895d69bfbd49166d9c83 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 11:56:27 -0800
Subject: [PATCH 13/29] remove the table classes in favor of lists

---
 docs/utilities/flexbox.md | 93 ---------------------------------------
 1 file changed, 93 deletions(-)

diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index a05c117e7f9f..6b3d87050ac8 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -29,37 +29,6 @@ Responsive variations also exist for `.d-flex` and `.d-inline-flex`.
 - `.d{{ bp.abbr }}-flex`
 - `.d{{ bp.abbr }}-inline-flex`{% endfor %}
 
-<table class="table-responsive" hidden>
-  <thead>
-    <tr class="bg-faded">
-      <th>Class</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    {% for bp in site.data.breakpoints %}
-    <tr>
-      <td>
-        <code>.d{{ bp.abbr }}-flex</code>
-      </td>
-      <td>
-        Sets <code>display: flex;</code> on viewports {{ bp.min-width }} wide and up
-      </td>
-    </tr>
-    {% endfor %}
-    {% for bp in site.data.breakpoints %}
-    <tr>
-      <td>
-        <code>.d{{ bp.abbr }}-inline-flex</code>
-      </td>
-      <td>
-        Sets <code>display: inline-flex;</code> on viewports {{ bp.min-width }} wide and up
-      </td>
-    </tr>
-    {% endfor %}
-  </tbody>
-</table>
-
 ## Direction
 
 Set the direction of flex items in a flex container with direction utilities. In most cases you can omit the horizontal class here as the browser default is `row`. However, you may encounter situations where you needed to explicitly set this value (like responsive layouts).
@@ -90,37 +59,6 @@ Responsive variations also exist for `.flex-row` and `.flex-column`.
 - `.flex{{ bp.abbr }}-row`
 - `.flex{{ bp.abbr }}-column`{% endfor %}
 
-<table class="table-responsive" hidden>
-  <thead>
-    <tr class="bg-faded">
-      <th>Class</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    {% for bp in site.data.breakpoints %}
-    <tr>
-      <td>
-        <code>.flex{{ bp.abbr }}-row</code>
-      </td>
-      <td>
-        Sets <code>flex-direction: row;</code> on viewports {{ bp.min-width }} wide and up
-      </td>
-    </tr>
-    {% endfor %}
-    {% for bp in site.data.breakpoints %}
-    <tr>
-      <td>
-        <code>.flex{{ bp.abbr }}-column</code>
-      </td>
-      <td>
-        Sets <code>flex-direction: column;</code> on viewports {{ bp.min-width }} wide and up
-      </td>
-    </tr>
-    {% endfor %}
-  </tbody>
-</table>
-
 ## Wrap
 
 Change how flex items wrap in a flex container. Choose from no wrapping at all (the browser default) with `.flex-nowrap`, or enable wrapping with `.flex-wrap`.
@@ -170,34 +108,3 @@ Responsive variations also exist for `.flex-nowrap` and `.flex-wrap`.
 {% for bp in site.data.breakpoints %}
 - `.flex{{ bp.abbr }}-nowrap`
 - `.flex{{ bp.abbr }}-wrap`{% endfor %}
-
-<table class="table-responsive" hidden>
-  <thead>
-    <tr class="bg-faded">
-      <th>Class</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    {% for bp in site.data.breakpoints %}
-    <tr>
-      <td>
-        <code>.flex{{ bp.abbr }}-nowrap</code>
-      </td>
-      <td>
-        Sets <code>flex-wrap: nowrap;</code> on viewports {{ bp.min-width }} wide and up
-      </td>
-    </tr>
-    {% endfor %}
-    {% for bp in site.data.breakpoints %}
-    <tr>
-      <td>
-        <code>.flex{{ bp.abbr }}-wrap</code>
-      </td>
-      <td>
-        Sets <code>flex-wrap: wrap;</code> on viewports {{ bp.min-width }} wide and up
-      </td>
-    </tr>
-    {% endfor %}
-  </tbody>
-</table>

From cd5aba9c892a70c2b0502301f3382053610bb51b Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 11:57:11 -0800
Subject: [PATCH 14/29] duplicate of the .flex-fill util

---
 scss/utilities/_flex.scss | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/scss/utilities/_flex.scss b/scss/utilities/_flex.scss
index c9783c2c8a86..7eb01385e295 100644
--- a/scss/utilities/_flex.scss
+++ b/scss/utilities/_flex.scss
@@ -60,9 +60,6 @@
     .align-content#{$infix}-around   { align-content: space-around !important; }
     .align-content#{$infix}-stretch  { align-content: stretch !important; }
 
-    // Item
-    .flex#{$infix}-auto { flex: 1 1 auto !important; }
-
     .align-self#{$infix}-auto        { align-self: auto !important; }
     .align-self#{$infix}-start       { align-self: flex-start !important; }
     .align-self#{$infix}-end         { align-self: flex-end !important; }

From 2d15a1ceb391eafa5b58529eed8085c77240ed36 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 12:40:55 -0800
Subject: [PATCH 15/29] indentation

---
 docs/utilities/flexbox.md | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index 6b3d87050ac8..2acd1fed4926 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -65,21 +65,21 @@ Change how flex items wrap in a flex container. Choose from no wrapping at all (
 
 {% example html %}
 <div class="d-flex flex-nowrap bd-highlight">
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
-<div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
 </div>
 {% endexample %}
 

From cd7fd44f93220ab456b2d38b08cafa141ded3079 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 12:54:01 -0800
Subject: [PATCH 16/29] document justify-content and align-items utils

---
 docs/utilities/flexbox.md | 65 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index 2acd1fed4926..bc2a9cdb0e8b 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -108,3 +108,68 @@ Responsive variations also exist for `.flex-nowrap` and `.flex-wrap`.
 {% for bp in site.data.breakpoints %}
 - `.flex{{ bp.abbr }}-nowrap`
 - `.flex{{ bp.abbr }}-wrap`{% endfor %}
+
+## Justify content
+
+Use `justify-content` utilities on flexbox containers to change the alignment of flex items on the main axis (the x-axis to start, y-axis if `flex-direction: column`). Choose from `start` (browser default), `end`, `center`, `between`, or `around`.
+
+{% example html %}
+<div class="d-flex justify-content-start bd-highlight mb-3">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+<div class="d-flex justify-content-end bd-highlight mb-3">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+<div class="d-flex justify-content-center bd-highlight mb-3">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+<div class="d-flex justify-content-between bd-highlight mb-3">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+<div class="d-flex justify-content-around bd-highlight">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+{% endexample %}
+
+
+## Align items
+
+Use `align-items` utilities on flexbox containers to change the alignment of flex items on the cross axis (the y-axis to start, x-axis if `flex-direction: column`). Choose from `start` (browser default), `end`, `center`, `baseline`, or `stretch`.
+
+{% example html %}
+<div class="d-flex align-items-start bd-highlight mb-3" style="height: 100px">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+<div class="d-flex align-items-end bd-highlight mb-3" style="height: 100px">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+<div class="d-flex align-items-center bd-highlight mb-3" style="height: 100px">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+<div class="d-flex align-items-baseline bd-highlight mb-3" style="height: 100px">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+<div class="d-flex align-items-stretch bd-highlight" style="height: 100px">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+{% endexample %}

From c3ab76dda1a3b7609c424d3f4e87b1033d116352 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 13:15:55 -0800
Subject: [PATCH 17/29] change presentation of those utils docs

---
 docs/utilities/flexbox.md | 103 +++++++++++++++++++++++++-------------
 1 file changed, 68 insertions(+), 35 deletions(-)

diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index bc2a9cdb0e8b..935922fb905e 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -113,49 +113,82 @@ Responsive variations also exist for `.flex-nowrap` and `.flex-wrap`.
 
 Use `justify-content` utilities on flexbox containers to change the alignment of flex items on the main axis (the x-axis to start, y-axis if `flex-direction: column`). Choose from `start` (browser default), `end`, `center`, `between`, or `around`.
 
-{% example html %}
-<div class="d-flex justify-content-start bd-highlight mb-3">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-</div>
-<div class="d-flex justify-content-end bd-highlight mb-3">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-</div>
-<div class="d-flex justify-content-center bd-highlight mb-3">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-</div>
-<div class="d-flex justify-content-between bd-highlight mb-3">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-</div>
-<div class="d-flex justify-content-around bd-highlight">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
+<div class="bd-example">
+  <div class="d-flex justify-content-start bd-highlight mb-3">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex justify-content-end bd-highlight mb-3">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex justify-content-center bd-highlight mb-3">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex justify-content-between bd-highlight mb-3">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex justify-content-around bd-highlight">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
 </div>
-{% endexample %}
+
+{% highlight html %}
+<div class="d-flex justify-content-start">...</div>
+<div class="d-flex justify-content-end">...</div>
+<div class="d-flex justify-content-center">...</div>
+<div class="d-flex justify-content-between">...</div>
+<div class="d-flex justify-content-around">...</div>
+{% endhighlight %}
 
 
 ## Align items
 
 Use `align-items` utilities on flexbox containers to change the alignment of flex items on the cross axis (the y-axis to start, x-axis if `flex-direction: column`). Choose from `start` (browser default), `end`, `center`, `baseline`, or `stretch`.
 
-{% example html %}
-<div class="d-flex align-items-start bd-highlight mb-3" style="height: 100px">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
+<div class="bd-example">
+  <div class="d-flex align-items-start bd-highlight mb-3" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex align-items-end bd-highlight mb-3" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex align-items-center bd-highlight mb-3" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex align-items-baseline bd-highlight mb-3" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex align-items-stretch bd-highlight" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
 </div>
-<div class="d-flex align-items-end bd-highlight mb-3" style="height: 100px">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
+
+{% highlight html %}
+<div class="d-flex align-items-start">...</div>
+<div class="d-flex align-items-end">...</div>
+<div class="d-flex align-items-center">...</div>
+<div class="d-flex align-items-baseline">...</div>
+<div class="d-flex align-items-stretch">...</div>
+{% endhighlight %}
 </div>
 <div class="d-flex align-items-center bd-highlight mb-3" style="height: 100px">
   <div class="p-2 bd-highlight">Flex item</div>

From f998227faea690b99dcb5223764f0ea3138aa4e3 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 13:16:13 -0800
Subject: [PATCH 18/29] document align-content utils

---
 docs/utilities/flexbox.md | 155 ++++++++++++++++++++++++++++++++++----
 1 file changed, 142 insertions(+), 13 deletions(-)

diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index 935922fb905e..59d732f1c714 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -189,20 +189,149 @@ Use `align-items` utilities on flexbox containers to change the alignment of fle
 <div class="d-flex align-items-baseline">...</div>
 <div class="d-flex align-items-stretch">...</div>
 {% endhighlight %}
+
+## Align content
+
+Use `align-content` utilities on flexbox containers to align flex items *together* on the cross axis. Choose from `start` (browser default), `end`, `center`, `between`, `around`, or `stretch`. To demonstrate these utilities, we've enforced `flex-wrap: wrap` and increased the number of flex items.
+
+**Heads up!** This property has no affect on single rows of flex items.
+
+<div class="bd-example">
+  <div class="d-flex align-content-start flex-wrap bd-highlight mb-3" style="height: 200px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
 </div>
-<div class="d-flex align-items-center bd-highlight mb-3" style="height: 100px">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
+{% highlight html %}
+<div class="d-flex align-content-start flex-wrap">
+  ...
 </div>
-<div class="d-flex align-items-baseline bd-highlight mb-3" style="height: 100px">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
+{% endhighlight %}
+
+<div class="bd-example">
+  <div class="d-flex align-content-end flex-wrap bd-highlight mb-3" style="height: 200px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
 </div>
-<div class="d-flex align-items-stretch bd-highlight" style="height: 100px">
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
-  <div class="p-2 bd-highlight">Flex item</div>
+{% highlight html %}
+<div class="d-flex align-content-end flex-wrap">...</div>
+{% endhighlight %}
+
+<div class="bd-example">
+  <div class="d-flex align-content-center flex-wrap bd-highlight mb-3" style="height: 200px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
 </div>
-{% endexample %}
+{% highlight html %}
+<div class="d-flex align-content-center flex-wrap">...</div>
+{% endhighlight %}
+
+<div class="bd-example">
+  <div class="d-flex align-content-between flex-wrap bd-highlight mb-3" style="height: 200px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+</div>
+{% highlight html %}
+<div class="d-flex align-content-between flex-wrap">...</div>
+{% endhighlight %}
+
+<div class="bd-example">
+  <div class="d-flex align-content-around flex-wrap bd-highlight mb-3" style="height: 200px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+</div>
+{% highlight html %}
+<div class="d-flex align-content-around flex-wrap">...</div>
+{% endhighlight %}
+
+<div class="bd-example">
+  <div class="d-flex align-content-stretch flex-wrap bd-highlight mb-3" style="height: 200px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+</div>
+{% highlight html %}
+<div class="d-flex align-content-stretch flex-wrap">...</div>
+{% endhighlight %}

From 271509f2549b0e8b8ef6eb4be48cb6f990170edc Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 13:23:11 -0800
Subject: [PATCH 19/29] align-self docs

---
 docs/utilities/flexbox.md | 43 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index 59d732f1c714..8359bbe93bee 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -149,10 +149,9 @@ Use `justify-content` utilities on flexbox containers to change the alignment of
 <div class="d-flex justify-content-around">...</div>
 {% endhighlight %}
 
-
 ## Align items
 
-Use `align-items` utilities on flexbox containers to change the alignment of flex items on the cross axis (the y-axis to start, x-axis if `flex-direction: column`). Choose from `start` (browser default), `end`, `center`, `baseline`, or `stretch`.
+Use `align-items` utilities on flexbox containers to change the alignment of flex items on the cross axis (the y-axis to start, x-axis if `flex-direction: column`). Choose from `start`, `end`, `center`, `baseline`, or `stretch` (browser default).
 
 <div class="bd-example">
   <div class="d-flex align-items-start bd-highlight mb-3" style="height: 100px">
@@ -190,6 +189,46 @@ Use `align-items` utilities on flexbox containers to change the alignment of fle
 <div class="d-flex align-items-stretch">...</div>
 {% endhighlight %}
 
+## Align self
+
+Use `align-self` utilities on flexbox items to individually change their alignment on the cross axis (the y-axis to start, x-axis if `flex-direction: column`). Choose from the same options as `align-items`: `start`, `end`, `center`, `baseline`, or `stretch` (browser default).
+
+<div class="bd-example">
+  <div class="d-flex bd-highlight mb-3" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="align-self-start p-2 bd-highlight">Aligned flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex bd-highlight mb-3" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="align-self-end p-2 bd-highlight">Aligned flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex bd-highlight mb-3" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="align-self-center p-2 bd-highlight">Aligned flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex bd-highlight mb-3" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="align-self-baseline p-2 bd-highlight">Aligned flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+  <div class="d-flex bd-highlight" style="height: 100px">
+    <div class="p-2 bd-highlight">Flex item</div>
+    <div class="align-self-stretch p-2 bd-highlight">Aligned flex item</div>
+    <div class="p-2 bd-highlight">Flex item</div>
+  </div>
+</div>
+
+{% highlight html %}
+<div class="align-self-start">Aligned flex item</div>
+<div class="align-self-end">Aligned flex item</div>
+<div class="align-self-center">Aligned flex item</div>
+<div class="align-self-baseline">Aligned flex item</div>
+<div class="align-self-stretch">Aligned flex item</div>
+{% endhighlight %}
+
 ## Align content
 
 Use `align-content` utilities on flexbox containers to align flex items *together* on the cross axis. Choose from `start` (browser default), `end`, `center`, `between`, `around`, or `stretch`. To demonstrate these utilities, we've enforced `flex-wrap: wrap` and increased the number of flex items.

From 8eb0672b0dbd529773c40c7451b0b068c6a66c36 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 13:31:09 -0800
Subject: [PATCH 20/29] remove old flex utils, update docs to match

---
 docs/_includes/nav-home.html           |  2 +-
 docs/components/list-group.md          |  8 ++++----
 docs/components/navbar.md              |  2 +-
 docs/examples/album/index.html         |  2 +-
 docs/examples/justified-nav/index.html |  2 +-
 docs/layout/grid.md                    | 26 +++++++++++++-------------
 scss/utilities/_flex.scss              | 21 ---------------------
 7 files changed, 21 insertions(+), 42 deletions(-)

diff --git a/docs/_includes/nav-home.html b/docs/_includes/nav-home.html
index e325d86052d1..3ba8520e0420 100644
--- a/docs/_includes/nav-home.html
+++ b/docs/_includes/nav-home.html
@@ -25,7 +25,7 @@
     </nav>
     {% endcomment %}
 
-    <div class="d-flex flex-items-between hidden-lg-up">
+    <div class="d-flex justify-content-between hidden-lg-up">
       <a class="navbar-brand" href="{{ site.baseurl }}/">
         Bootstrap
       </a>
diff --git a/docs/components/list-group.md b/docs/components/list-group.md
index 1c13847249b9..0e06d3a7f26e 100644
--- a/docs/components/list-group.md
+++ b/docs/components/list-group.md
@@ -27,19 +27,19 @@ The most basic list group is simply an unordered list with list items, and the p
 
 ## Badge
 
-Add badges to any list group item to show unread counts, activity, and more with the help of some utilities. Note the [`flex-items-between` utility class]({{ site.baseurl }}/layout/grid/#horizontal-alignment), the badge's placement, and the lack of a float and margin utilities on the badges.
+Add badges to any list group item to show unread counts, activity, and more with the help of some utilities. Note the [`justify-content-between` utility class]({{ site.baseurl }}/layout/grid/#horizontal-alignment), the badge's placement, and the lack of a float and margin utilities on the badges.
 
 {% highlight html %}
 <ul class="list-group">
-  <li class="list-group-item flex-items-between">
+  <li class="list-group-item justify-content-between">
     Cras justo odio
     <span class="badge badge-default badge-pill">14</span>
   </li>
-  <li class="list-group-item flex-items-between">
+  <li class="list-group-item justify-content-between">
     Dapibus ac facilisis in
     <span class="badge badge-default badge-pill">2</span>
   </li>
-  <li class="list-group-item flex-items-between">
+  <li class="list-group-item justify-content-between">
     Morbi leo risus
     <span class="badge badge-default badge-pill">1</span>
   </li>
diff --git a/docs/components/navbar.md b/docs/components/navbar.md
index 57e0bad7a185..2ee4c563ff8f 100644
--- a/docs/components/navbar.md
+++ b/docs/components/navbar.md
@@ -202,7 +202,7 @@ Place various form controls and components within a navbar with `.form-inline`.
 Align the contents of your inline forms with utilities as needed.
 
 {% example html %}
-<nav class="navbar navbar-light bg-faded flex-items-right">
+<nav class="navbar navbar-light bg-faded justify-content-end">
   <form class="form-inline">
     <input class="form-control mr-sm-2" type="text" placeholder="Search">
     <button class="btn btn-outline-success my-2 my-sm-0" type="submit">Search</button>
diff --git a/docs/examples/album/index.html b/docs/examples/album/index.html
index 15a43ff507ee..05fc659bb64d 100644
--- a/docs/examples/album/index.html
+++ b/docs/examples/album/index.html
@@ -39,7 +39,7 @@ <h4 class="text-white">Contact</h4>
       </div>
     </div>
     <div class="navbar navbar-inverse bg-inverse">
-      <div class="container d-flex flex-items-between">
+      <div class="container d-flex justify-content-between">
         <a href="#" class="navbar-brand">Album</a>
         <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarHeader" aria-controls="navbarHeader" aria-expanded="false" aria-label="Toggle navigation">
           <span class="navbar-toggler-icon"></span>
diff --git a/docs/examples/justified-nav/index.html b/docs/examples/justified-nav/index.html
index 913eaefbbfb7..f12a9efe7a4e 100644
--- a/docs/examples/justified-nav/index.html
+++ b/docs/examples/justified-nav/index.html
@@ -30,7 +30,7 @@ <h3 class="text-muted">Project name</h3>
             <span class="navbar-toggler-icon"></span>
           </button>
           <div class="collapse navbar-toggleable-md" id="navbarCollapse">
-            <ul class="nav navbar-nav text-md-center flex-items-md-between">
+            <ul class="nav navbar-nav text-md-center justify-content-md-between">
               <li class="nav-item active">
                 <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
               </li>
diff --git a/docs/layout/grid.md b/docs/layout/grid.md
index d7391025fd31..efdf3a93782d 100644
--- a/docs/layout/grid.md
+++ b/docs/layout/grid.md
@@ -204,7 +204,7 @@ Using the `col-{breakpoint}-auto` classes, columns can size itself based on the
 <div class="bd-example-row">
 {% example html %}
 <div class="container">
-  <div class="row flex-items-md-center">
+  <div class="row justify-content-md-center">
     <div class="col col-lg-2">
       1 of 3
     </div>
@@ -304,10 +304,10 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
 
 ### Vertical alignment
 
-<div class="bd-example-row">
+<div class="bd-example-row bd-example-row-flex-cols">
 {% example html %}
 <div class="container">
-  <div class="row flex-items-top">
+  <div class="row align-items-start">
     <div class="col">
       One of three columns
     </div>
@@ -318,7 +318,7 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
       One of three columns
     </div>
   </div>
-  <div class="row flex-items-middle">
+  <div class="row align-items-center">
     <div class="col">
       One of three columns
     </div>
@@ -329,7 +329,7 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
       One of three columns
     </div>
   </div>
-  <div class="row flex-items-bottom">
+  <div class="row align-items-end">
     <div class="col">
       One of three columns
     </div>
@@ -348,13 +348,13 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
 {% example html %}
 <div class="container">
   <div class="row">
-    <div class="col flex-top">
+    <div class="col align-self-start">
       One of three columns
     </div>
-    <div class="col flex-middle">
+    <div class="col align-self-center">
       One of three columns
     </div>
-    <div class="col flex-bottom">
+    <div class="col align-self-end">
       One of three columns
     </div>
   </div>
@@ -367,7 +367,7 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
 <div class="bd-example-row">
 {% example html %}
 <div class="container">
-  <div class="row flex-items-left">
+  <div class="row justify-content-start">
     <div class="col-4">
       One of two columns
     </div>
@@ -375,7 +375,7 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
       One of two columns
     </div>
   </div>
-  <div class="row flex-items-center">
+  <div class="row justify-content-center">
     <div class="col-4">
       One of two columns
     </div>
@@ -383,7 +383,7 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
       One of two columns
     </div>
   </div>
-  <div class="row flex-items-right">
+  <div class="row justify-content-end">
     <div class="col-4">
       One of two columns
     </div>
@@ -391,7 +391,7 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
       One of two columns
     </div>
   </div>
-  <div class="row flex-items-around">
+  <div class="row justify-content-around">
     <div class="col-4">
       One of two columns
     </div>
@@ -399,7 +399,7 @@ Use flexbox alignment utilities to vertically and horizontally align columns.
       One of two columns
     </div>
   </div>
-  <div class="row flex-items-between">
+  <div class="row justify-content-between">
     <div class="col-4">
       One of two columns
     </div>
diff --git a/scss/utilities/_flex.scss b/scss/utilities/_flex.scss
index 7eb01385e295..93b666378752 100644
--- a/scss/utilities/_flex.scss
+++ b/scss/utilities/_flex.scss
@@ -11,27 +11,6 @@
     .flex#{$infix}-last      { order: 1; }
     .flex#{$infix}-unordered { order: 0; }
 
-    // Alignment for every item
-    .flex-items#{$infix}-top    { align-items: flex-start; }
-    .flex-items#{$infix}-middle { align-items: center; }
-    .flex-items#{$infix}-bottom { align-items: flex-end; }
-
-    // Alignment per item
-    .flex#{$infix}-top    { align-self: flex-start; }
-    .flex#{$infix}-middle { align-self: center; }
-    .flex#{$infix}-bottom { align-self: flex-end; }
-
-    // Horizontal alignment of item
-    .flex-items#{$infix}-left    { justify-content: flex-start; }
-    .flex-items#{$infix}-center  { justify-content: center; }
-    .flex-items#{$infix}-right   { justify-content: flex-end; }
-    .flex-items#{$infix}-around  { justify-content: space-around; }
-    .flex-items#{$infix}-between { justify-content: space-between; }
-
-    //
-    // New flex utils to replace and extend the ones above
-    //
-
     .flex#{$infix}-fill { flex: 1 1 auto; }
     .flex#{$infix}-justify { flex: 1 1 100%; }
 

From f99be7c87b5a2ef9a5084936020c2c69509dabac Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 23 Dec 2016 21:47:30 -0800
Subject: [PATCH 21/29] remove unused utils, comment

---
 scss/utilities/_flex.scss | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/scss/utilities/_flex.scss b/scss/utilities/_flex.scss
index 93b666378752..ca713ef3e91f 100644
--- a/scss/utilities/_flex.scss
+++ b/scss/utilities/_flex.scss
@@ -6,14 +6,10 @@
   @include media-breakpoint-up($breakpoint) {
     $infix: breakpoint-infix($breakpoint, $grid-breakpoints);
 
-    // Flex column reordering
     .flex#{$infix}-first     { order: -1; }
     .flex#{$infix}-last      { order: 1; }
     .flex#{$infix}-unordered { order: 0; }
 
-    .flex#{$infix}-fill { flex: 1 1 auto; }
-    .flex#{$infix}-justify { flex: 1 1 100%; }
-
     .flex#{$infix}-row      { flex-direction: row !important; }
     .flex#{$infix}-column   { flex-direction: column !important; }
 

From 3baef00d7febf521c9288163ee010efd8e137b6a Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 24 Dec 2016 00:29:28 -0800
Subject: [PATCH 22/29] remove unused media vars, update numbers (oof) /cc @Quy

---
 scss/_variables.scss | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 412f944f530b..e09d7e8452b4 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -903,14 +903,7 @@ $breadcrumb-active-color:       $gray-light !default;
 $breadcrumb-divider:            "/" !default;
 
 
-// 32. Media objects
-
-$media-margin-top:            15px !default;
-$media-heading-margin-bottom:  5px !default;
-$media-alignment-padding-x:   10px !default;
-
-
-// 33. Carousel
+// 32. Carousel
 
 $carousel-control-color:                      $white !default;
 $carousel-control-width:                      15% !default;
@@ -932,14 +925,14 @@ $carousel-control-next-icon-bg: str-replace(url("data:image/svg+xml;charset=utf8
 $carousel-transition:           transform .6s ease-in-out !default;
 
 
-// 34. Close
+// 33. Close
 
 $close-font-weight:           $font-weight-bold !default;
 $close-color:                 $black !default;
 $close-text-shadow:           0 1px 0 $white !default;
 
 
-// 35. Code
+// 34. Code
 
 $code-font-size:              90% !default;
 $code-padding-x:              .4rem !default;

From 8d9f7a7052853ff460460060131b67e14a13ed3a Mon Sep 17 00:00:00 2001
From: Quy <quy@fluxbb.org>
Date: Sat, 24 Dec 2016 12:30:23 -0800
Subject: [PATCH 23/29] Update toc numbering (#21422)

---
 scss/_variables.scss | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/scss/_variables.scss b/scss/_variables.scss
index e09d7e8452b4..975754c56d4c 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -37,10 +37,9 @@
 // 29. Image thumbnails
 // 30. Figures
 // 31. Breadcrumbs
-// 32. Media objects
-// 33. Carousel
-// 34. Close
-// 35. Code
+// 32. Carousel
+// 33. Close
+// 34. Code
 
 @mixin _assert-ascending($map, $map-name) {
   $prev-key: null;

From 091a25bca5b24f3594f8aebc98910cb94ededa2e Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 24 Dec 2016 12:33:42 -0800
Subject: [PATCH 24/29] add order docs

---
 docs/utilities/flexbox.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index 8359bbe93bee..0c0cd5eedc55 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -229,6 +229,18 @@ Use `align-self` utilities on flexbox items to individually change their alignme
 <div class="align-self-stretch">Aligned flex item</div>
 {% endhighlight %}
 
+## Order
+
+Change the _visual_ order of specific flex items with a handful of `order` utilities. We only provide options for making an item first or last, as well as a reset to use the DOM order. As `order` takes any integer value (e.g., `5`), add custom CSS for any additional values needed.
+
+{% example html %}
+<div class="d-flex flex-nowrap bd-highlight">
+  <div class="flex-last p-2 bd-highlight">First flex item</div>
+  <div class="p-2 bd-highlight">Second flex item</div>
+  <div class="flex-first p-2 bd-highlight">Third flex item</div>
+</div>
+{% endexample %}
+
 ## Align content
 
 Use `align-content` utilities on flexbox containers to align flex items *together* on the cross axis. Choose from `start` (browser default), `end`, `center`, `between`, `around`, or `stretch`. To demonstrate these utilities, we've enforced `flex-wrap: wrap` and increased the number of flex items.

From d0d1487e2b14e593f02f5c4fa6aac677e819c3ea Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 24 Dec 2016 12:35:08 -0800
Subject: [PATCH 25/29] rip numbers

---
 scss/_variables.scss | 134 +++++++++++++++++++++----------------------
 1 file changed, 67 insertions(+), 67 deletions(-)

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 975754c56d4c..ea5031f33605 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -6,40 +6,40 @@
 
 // Table of Contents
 //
-//  1. Colors
-//  2. Options
-//  3. Spacing
-//  4. Body
-//  5. Links
-//  6. Grid breakpoints
-//  7. Grid containers
-//  8. Grid columns
-//  9. Fonts
-// 10. Components
-// 11. Tables
-// 12. Buttons
-// 13. Forms
-// 14. Dropdowns
-// 15. Z-index master list
-// 16. Navbar
-// 17. Navs
-// 18. Pagination
-// 19. Jumbotron
-// 20. Form states and alerts
-// 21. Cards
-// 22. Tooltips
-// 23. Popovers
-// 24. Badges
-// 25. Modals
-// 26. Alerts
-// 27. Progress bars
-// 28. List group
-// 29. Image thumbnails
-// 30. Figures
-// 31. Breadcrumbs
-// 32. Carousel
-// 33. Close
-// 34. Code
+// Colors
+// Options
+// Spacing
+// Body
+// Links
+// Grid breakpoints
+// Grid containers
+// Grid columns
+// Fonts
+// Components
+// Tables
+// Buttons
+// Forms
+// Dropdowns
+// Z-index master list
+// Navbar
+// Navs
+// Pagination
+// Jumbotron
+// Form states and alerts
+// Cards
+// Tooltips
+// Popovers
+// Badges
+// Modals
+// Alerts
+// Progress bars
+// List group
+// Image thumbnails
+// Figures
+// Breadcrumbs
+// Carousel
+// Close
+// Code
 
 @mixin _assert-ascending($map, $map-name) {
   $prev-key: null;
@@ -87,7 +87,7 @@
 // Variable format should follow the `$component-modifier-state-property` order.
 
 
-// 1. Colors
+// Colors
 //
 // Grayscale and brand colors for use across Bootstrap.
 
@@ -119,7 +119,7 @@ $brand-danger:              $red !default;
 $brand-inverse:             $gray-dark !default;
 
 
-// 2. Options
+// Options
 //
 // Quickly modify global styling by enabling or disabling optional features.
 
@@ -132,7 +132,7 @@ $enable-grid-classes:       true !default;
 $enable-print-styles:       true !default;
 
 
-// 3. Spacing
+// Spacing
 //
 // Control the default styling of most Bootstrap elements by modifying these
 // variables. Mostly focused on spacing.
@@ -170,7 +170,7 @@ $spacers: (
 $border-width: 1px !default;
 
 
-// 4. Body
+// Body
 //
 // Settings for the `<body>` element.
 
@@ -180,7 +180,7 @@ $inverse-bg:    $gray-dark !default;
 $inverse-color: $gray-lighter !default;
 
 
-// 5. Links
+// Links
 //
 // Style anchor elements.
 
@@ -190,7 +190,7 @@ $link-hover-color:      darken($link-color, 15%) !default;
 $link-hover-decoration: underline !default;
 
 
-// 6. Grid breakpoints
+// Grid breakpoints
 //
 // Define the minimum dimensions at which your layout will change,
 // adapting to different screen sizes, for use in media queries.
@@ -206,7 +206,7 @@ $grid-breakpoints: (
 @include _assert-starts-at-zero($grid-breakpoints);
 
 
-// 7. Grid containers
+// Grid containers
 //
 // Define the maximum width of `.container` for different screen sizes.
 
@@ -219,7 +219,7 @@ $container-max-widths: (
 @include _assert-ascending($container-max-widths, "$container-max-widths");
 
 
-// 8. Grid columns
+// Grid columns
 //
 // Set the number of columns and specify the width of the gutters.
 
@@ -233,7 +233,7 @@ $grid-gutter-widths: (
   xl: $grid-gutter-width-base
 ) !default;
 
-// 9. Fonts
+// Fonts
 //
 // Font, line-height, and color for body text, headings, and more.
 
@@ -306,7 +306,7 @@ $nested-kbd-font-weight: $font-weight-bold !default;
 $list-inline-padding: 5px !default;
 
 
-// 10. Components
+// Components
 //
 // Define common padding and border radius sizes and more.
 
@@ -328,7 +328,7 @@ $transition-fade:        opacity .15s linear !default;
 $transition-collapse:    height .35s ease !default;
 
 
-// 11. Tables
+// Tables
 //
 // Customizes the `.table` component with basic values, each used across all table variations.
 
@@ -351,7 +351,7 @@ $table-border-width:            $border-width !default;
 $table-border-color:            $gray-lighter !default;
 
 
-// 12. Buttons
+// Buttons
 //
 // For each of Bootstrap's buttons, define text, background and border color.
 
@@ -405,7 +405,7 @@ $btn-border-radius-sm:           $border-radius-sm !default;
 $btn-transition:                 all .2s ease-in-out !default;
 
 
-// 13. Forms
+// Forms
 
 $input-padding-x:                .75rem !default;
 $input-padding-y:                .5rem !default;
@@ -540,7 +540,7 @@ $form-icon-danger-color: $brand-danger !default;
 $form-icon-danger: str-replace(url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='#{$form-icon-danger-color}' viewBox='-2 -2 7 7'%3E%3Cpath stroke='%23d9534f' d='M0 0l3 3m0-3L0 3'/%3E%3Ccircle r='.5'/%3E%3Ccircle cx='3' r='.5'/%3E%3Ccircle cy='3' r='.5'/%3E%3Ccircle cx='3' cy='3' r='.5'/%3E%3C/svg%3E"), "#", "%23") !default;
 
 
-// 14. Dropdowns
+// Dropdowns
 //
 // Dropdown menu container and contents.
 
@@ -567,7 +567,7 @@ $dropdown-item-padding-x:        1.5rem !default;
 $dropdown-header-color:          $gray-light !default;
 
 
-// 15. Z-index master list
+// Z-index master list
 //
 // Warning: Avoid customizing these values. They're used for a bird's eye view
 // of components dependent on the z-axis and are designed to all work together.
@@ -583,7 +583,7 @@ $zindex-popover:           1060 !default;
 $zindex-tooltip:           1070 !default;
 
 
-// 16. Navbar
+// Navbar
 
 $navbar-border-radius:              $border-radius !default;
 $navbar-padding-x:                  $spacer !default;
@@ -637,7 +637,7 @@ $nav-pills-active-link-color: $component-active-color !default;
 $nav-pills-active-link-bg:    $component-active-bg !default;
 
 
-// 18. Pagination
+// Pagination
 
 $pagination-padding-x:                .75rem !default;
 $pagination-padding-y:                .5rem !default;
@@ -665,13 +665,13 @@ $pagination-disabled-bg:               $white !default;
 $pagination-disabled-border:           #ddd !default;
 
 
-// 19. Jumbotron
+// Jumbotron
 
 $jumbotron-padding:              2rem !default;
 $jumbotron-bg:                   $gray-lighter !default;
 
 
-// 20. Form states and alerts
+// Form states and alerts
 //
 // Define colors for form feedback states and, by default, alerts.
 
@@ -693,7 +693,7 @@ $state-danger-bg:                #f2dede !default;
 $state-danger-border:            darken($state-danger-bg, 5%) !default;
 
 
-// 21. Cards
+// Cards
 
 $card-spacer-x:            1.25rem !default;
 $card-spacer-y:            .75rem !default;
@@ -715,7 +715,7 @@ $card-columns-gap:          1.25rem !default;
 $card-columns-margin:       $card-spacer-y !default;
 
 
-// 22. Tooltips
+// Tooltips
 
 $tooltip-max-width:           200px !default;
 $tooltip-color:               $white !default;
@@ -729,7 +729,7 @@ $tooltip-arrow-width:         5px !default;
 $tooltip-arrow-color:         $tooltip-bg !default;
 
 
-// 23. Popovers
+// Popovers
 
 $popover-inner-padding:               1px !default;
 $popover-bg:                          $white !default;
@@ -752,7 +752,7 @@ $popover-arrow-outer-width:           ($popover-arrow-width + 1px) !default;
 $popover-arrow-outer-color:           fade-in($popover-border-color, .05) !default;
 
 
-// 24. Badges
+// Badges
 
 $badge-default-bg:            $gray-light !default;
 $badge-primary-bg:            $brand-primary !default;
@@ -774,7 +774,7 @@ $badge-pill-padding-x:        .6em !default;
 $badge-pill-border-radius:    10rem !default;
 
 
-// 25. Modals
+// Modals
 
 // Padding applied to the modal body
 $modal-inner-padding:         15px !default;
@@ -805,7 +805,7 @@ $modal-sm:                    300px !default;
 $modal-transition:            transform .3s ease-out !default;
 
 
-// 26. Alerts
+// Alerts
 //
 // Define alert colors, border radius, and padding.
 
@@ -833,7 +833,7 @@ $alert-danger-text:           $state-danger-text !default;
 $alert-danger-border:         $state-danger-border !default;
 
 
-// 27. Progress bars
+// Progress bars
 
 $progress-bg:                 $gray-lighter !default;
 $progress-bar-color:          $brand-primary !default;
@@ -847,7 +847,7 @@ $progress-bar-danger-bg:      $brand-danger !default;
 $progress-bar-info-bg:        $brand-info !default;
 
 
-// 28. List group
+// List group
 
 $list-group-bg:                 $white !default;
 $list-group-border-color:       rgba($black,.125) !default;
@@ -873,7 +873,7 @@ $list-group-item-padding-y:             .75rem !default;
 $list-group-item-heading-margin-bottom: 5px !default;
 
 
-// 29. Image thumbnails
+// Image thumbnails
 
 $thumbnail-padding:           .25rem !default;
 $thumbnail-bg:                $body-bg !default;
@@ -884,13 +884,13 @@ $thumbnail-box-shadow:        0 1px 2px rgba($black,.075) !default;
 $thumbnail-transition:        all .2s ease-in-out !default;
 
 
-// 30. Figures
+// Figures
 
 $figure-caption-font-size: 90% !default;
 $figure-caption-color:     $gray-light !default;
 
 
-// 31. Breadcrumbs
+// Breadcrumbs
 
 $breadcrumb-padding-y:          .75rem !default;
 $breadcrumb-padding-x:          1rem !default;
@@ -902,7 +902,7 @@ $breadcrumb-active-color:       $gray-light !default;
 $breadcrumb-divider:            "/" !default;
 
 
-// 32. Carousel
+// Carousel
 
 $carousel-control-color:                      $white !default;
 $carousel-control-width:                      15% !default;
@@ -924,14 +924,14 @@ $carousel-control-next-icon-bg: str-replace(url("data:image/svg+xml;charset=utf8
 $carousel-transition:           transform .6s ease-in-out !default;
 
 
-// 33. Close
+// Close
 
 $close-font-weight:           $font-weight-bold !default;
 $close-color:                 $black !default;
 $close-text-shadow:           0 1px 0 $white !default;
 
 
-// 34. Code
+// Code
 
 $code-font-size:              90% !default;
 $code-padding-x:              .4rem !default;

From 6109687ab3ae0f1984335558d9e96d7d8bec4fec Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 24 Dec 2016 14:04:11 -0800
Subject: [PATCH 26/29] nest modal examples css

---
 docs/assets/scss/_component-examples.scss | 32 ++++++++++++-----------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/docs/assets/scss/_component-examples.scss b/docs/assets/scss/_component-examples.scss
index c13218f0f1d2..f08726484fab 100644
--- a/docs/assets/scss/_component-examples.scss
+++ b/docs/assets/scss/_component-examples.scss
@@ -241,21 +241,23 @@
 
 // Example modals
 .bd-example-modal {
-  background-color: #f5f5f5;
-}
-.bd-example-modal .modal {
-  position: relative;
-  top: auto;
-  right: auto;
-  bottom: auto;
-  left: auto;
-  z-index: 1;
-  display: block;
-}
-.bd-example-modal .modal-dialog {
-  left: auto;
-  margin-right: auto;
-  margin-left: auto;
+  background-color: #fafafa;
+
+  .modal {
+    position: relative;
+    top: auto;
+    right: auto;
+    bottom: auto;
+    left: auto;
+    z-index: 1;
+    display: block;
+  }
+
+  .modal-dialog {
+    left: auto;
+    margin-right: auto;
+    margin-left: auto;
+  }
 }
 
 // Example dropdowns

From cf01923b8cf87a258c84cccc18c56346e80f180a Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 24 Dec 2016 14:04:44 -0800
Subject: [PATCH 27/29] started fixing nested .bd-example stuff, then rewrote
 the modal docs

- better table of contents and overall structure

- clearer examples of modal contents, longer modals, and modal options
---
 docs/components/modal.md | 436 +++++++++++++++++++++++++--------------
 1 file changed, 278 insertions(+), 158 deletions(-)

diff --git a/docs/components/modal.md b/docs/components/modal.md
index 5b482f93b707..7251c384287d 100644
--- a/docs/components/modal.md
+++ b/docs/components/modal.md
@@ -5,42 +5,40 @@ description: Learn how to use Bootstrap's modals to add dialog prompts to your s
 group: components
 ---
 
-Modals are streamlined, but flexible, dialog prompts with the minimum required functionality and smart defaults.
+Modals are streamlined, but flexible dialog prompts powered by JavaScript. They support a number of use cases from user notification to completely custom content and feature a handful of helpful subcomponents, sizes, and more.
 
 ## Contents
 
 * Will be replaced with the ToC, excluding the "Contents" header
 {:toc}
 
-**Due to how HTML5 defines its semantics, [the `autofocus` HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-autofocus) has no effect in Bootstrap modals.** To achieve the same effect, use some custom JavaScript:
+## How it works
 
-{% highlight js %}
-$('#myModal').on('shown.bs.modal', function () {
-  $('#myInput').focus()
-})
-{% endhighlight %}
+Before getting started with Bootstrap's modal component, be sure to read the following as our menu options have recently changed.
 
-{% callout warning %}
-#### Multiple open modals not supported
+- Modals are built with HTML, CSS, and JavaScript. They're positioned over everything else in the document and remove scroll from the `<body>` so that modal content scrolls instead.
+- Clicking on the modal "backdrop" will automatically close the modal.
+- Bootstrap only supports one modal window at a time. Nested modals aren't supported as we believe them to be poor user experiences.
+- Modal's use `position: fixed`, which can sometimes be a bit particular about it's rendering. Whenever possible, place your modal HTML in a top-level position to avoid potential interference from other elements. You'll likely run into issues when nesting a `.modal` within another fixed element.
+- One again, due to `position: fixed`, there are some caveats with using modals on mobile devices. [See our browser support docs]({{ site.baseurl }}/getting-started/browsers-devices/#modals-and-dropdowns-on-mobile) for details.
+- Lastly, the `autofocus` HTML attribute has no affect in modals. Here's how you can achieve the same effect with custom JavaScript.
 
-Be sure not to open a modal while another is still visible. Showing more than one modal at a time requires custom code.
-{% endcallout %}
+Keep reading for demos and usage guidelines.
 
-{% callout warning %}
-#### Modal markup placement
 
-Always try to place a modal's HTML code in a top-level position in your document to avoid other components affecting the modal's appearance and/or functionality. Placing it within a `position: fixed;` element may adversely affect placement.
-{% endcallout %}
+- Due to how HTML5 defines its semantics, [the `autofocus` HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-autofocus) has no effect in Bootstrap modals. To achieve the same effect, use some custom JavaScript:
 
-{% callout warning %}
-#### Mobile device caveats
+{% highlight js %}
+$('#myModal').on('shown.bs.modal', function () {
+  $('#myInput').focus()
+})
+{% endhighlight %}
 
-There are some caveats regarding using modals on mobile devices. [See our browser support docs]({{ site.baseurl }}/getting-started/browsers-devices/#modals-and-dropdowns-on-mobile) for details.
-{% endcallout %}
+## Examples
 
-### Static example
+### Modal components
 
-A rendered modal with header, body, and set of actions in the footer.
+Below is a _static_ modal example (meaning its `position` and `display` have been overridden). Included are the modal header, modal body (required for `padding`), and modal footer (optional). We ask that you include modal headers with dismiss actions whenever possible, or provide another explicit dismiss action.
 
 <div class="bd-example bd-example-modal">
   <div class="modal">
@@ -50,18 +48,18 @@ A rendered modal with header, body, and set of actions in the footer.
           <button type="button" class="close" data-dismiss="modal" aria-label="Close">
             <span aria-hidden="true">&times;</span>
           </button>
-          <h4 class="modal-title">Modal title</h4>
+          <h5 class="modal-title">Modal title</h5>
         </div>
         <div class="modal-body">
-          <p>One fine body&hellip;</p>
+          <p>Modal body text goes here.</p>
         </div>
         <div class="modal-footer">
           <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
           <button type="button" class="btn btn-primary">Save changes</button>
         </div>
-      </div><!-- /.modal-content -->
-    </div><!-- /.modal-dialog -->
-  </div><!-- /.modal -->
+      </div>
+    </div>
+  </div>
 </div>
 
 {% highlight html %}
@@ -72,87 +70,65 @@ A rendered modal with header, body, and set of actions in the footer.
         <button type="button" class="close" data-dismiss="modal" aria-label="Close">
           <span aria-hidden="true">&times;</span>
         </button>
-        <h4 class="modal-title">Modal title</h4>
+        <h5 class="modal-title">Modal title</h5>
       </div>
       <div class="modal-body">
-        <p>One fine body&hellip;</p>
+        <p>Modal body text goes here.</p>
       </div>
       <div class="modal-footer">
-        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
         <button type="button" class="btn btn-primary">Save changes</button>
+        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
       </div>
-    </div><!-- /.modal-content -->
-  </div><!-- /.modal-dialog -->
-</div><!-- /.modal -->
+    </div>
+  </div>
+</div>
 {% endhighlight %}
 
 ### Live demo
 
-Toggle a modal via JavaScript by clicking the button below. It will slide down and fade in from the top of the page.
+Toggle a working modal demo by clicking the button below. It will slide down and fade in from the top of the page.
 
-<div id="myModal" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
+<div id="exampleModal" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
   <div class="modal-dialog" role="document">
     <div class="modal-content">
-
       <div class="modal-header">
         <button type="button" class="close" data-dismiss="modal" aria-label="Close">
           <span aria-hidden="true">&times;</span>
         </button>
-        <h4 class="modal-title" id="myModalLabel">Modal title</h4>
+        <h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
       </div>
       <div class="modal-body">
-        <h4>Text in a modal</h4>
-        <p>Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</p>
-
-        <h4>Popover in a modal</h4>
-        <p>This <a href="#" role="button" class="btn btn-secondary popover-test" title="A Title" data-content="And here's some amazing content. It's very engaging. right?">button</a> should trigger a popover on click.</p>
-
-        <h4>Tooltips in a modal</h4>
-        <p><a href="#" class="tooltip-test" title="Tooltip">This link</a> and <a href="#" class="tooltip-test" title="Tooltip">that link</a> should have tooltips on hover.</p>
-
-        <hr>
-
-        <h4>Overflowing text to show scroll behavior</h4>
-        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
-        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
-        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
-        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
-        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
-        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
-        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
-        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
-        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+        <p>Woohoo, you're reading this text in a modal!</p>
       </div>
       <div class="modal-footer">
         <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
         <button type="button" class="btn btn-primary">Save changes</button>
       </div>
-
-    </div><!-- /.modal-content -->
-  </div><!-- /.modal-dialog -->
+    </div>
+  </div>
 </div>
 
-<div class="bd-example" style="padding-bottom: 24px;">
-  <button type="button" class="btn btn-primary btn-lg" data-toggle="modal" data-target="#myModal">
+<div class="bd-example">
+  <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
     Launch demo modal
   </button>
 </div>
 
 {% highlight html %}
 <!-- Button trigger modal -->
-<button type="button" class="btn btn-primary btn-lg" data-toggle="modal" data-target="#myModal">
+<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
   Launch demo modal
 </button>
 
 <!-- Modal -->
-<div class="modal fade" id="myModal" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
+<div class="modal fade" id="myModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
   <div class="modal-dialog" role="document">
     <div class="modal-content">
       <div class="modal-header">
         <button type="button" class="close" data-dismiss="modal" aria-label="Close">
           <span aria-hidden="true">&times;</span>
         </button>
-        <h4 class="modal-title" id="myModalLabel">Modal title</h4>
+        <h4 class="modal-title" id="exampleModalLabel">Modal title</h4>
       </div>
       <div class="modal-body">
         ...
@@ -166,108 +142,135 @@ Toggle a modal via JavaScript by clicking the button below. It will slide down a
 </div>
 {% endhighlight %}
 
-{% callout warning %}
-#### Make modals accessible
-
-Be sure to add `role="dialog"` and `aria-labelledby="..."`, referencing the modal title, to `.modal`, and `role="document"` to the `.modal-dialog` itself.
-
-Additionally, you may give a description of your modal dialog with `aria-describedby` on `.modal`.
-{% endcallout %}
-
-{% callout info %}
-#### Embedding YouTube videos
-
-Embedding YouTube videos in modals requires additional JavaScript not in Bootstrap to automatically stop playback and more. [See this helpful Stack Overflow post](https://stackoverflow.com/questions/18622508/bootstrap-3-and-youtube-in-modal) for more information.
-{% endcallout %}
-
-## Optional sizes
-
-Modals have two optional sizes, available via modifier classes to be placed on a `.modal-dialog`. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports.
-
-<div class="bd-example">
-  <button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-lg">Large modal</button>
-  <button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-sm">Small modal</button>
-</div>
+### Scrolling long content
 
-{% highlight html %}
-<!-- Large modal -->
-<button class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-lg">Large modal</button>
+When modals become too long for the user's viewport or device, they scroll independent of the page itself. Try the demo below to see what we mean.
 
-<div class="modal fade bd-example-modal-lg" tabindex="-1" role="dialog" aria-labelledby="myLargeModalLabel" aria-hidden="true">
-  <div class="modal-dialog modal-lg">
+<div id="exampleModalLong" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="exampleModalLongTitle" aria-hidden="true">
+  <div class="modal-dialog" role="document">
     <div class="modal-content">
-      ...
+      <div class="modal-header">
+        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
+          <span aria-hidden="true">&times;</span>
+        </button>
+        <h5 class="modal-title" id="exampleModalLongTitle">Modal title</h5>
+      </div>
+      <div class="modal-body">
+        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+        <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+        <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
+        <button type="button" class="btn btn-primary">Save changes</button>
+      </div>
     </div>
   </div>
 </div>
 
-<!-- Small modal -->
-<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-sm">Small modal</button>
-
-<div class="modal fade bd-example-modal-sm" tabindex="-1" role="dialog" aria-labelledby="mySmallModalLabel" aria-hidden="true">
-  <div class="modal-dialog modal-sm">
-    <div class="modal-content">
-      ...
-    </div>
-  </div>
+<div class="bd-example">
+  <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalLong">
+    Launch demo modal
+  </button>
 </div>
-{% endhighlight %}
 
-<div class="modal fade bd-example-modal-lg" tabindex="-1" role="dialog" aria-labelledby="myLargeModalLabel" aria-hidden="true">
-  <div class="modal-dialog modal-lg">
-    <div class="modal-content">
+{% highlight html %}
+<!-- Button trigger modal -->
+<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalLong">
+  Launch demo modal
+</button>
 
+<!-- Modal -->
+<div class="modal fade" id="exampleModalLong" tabindex="-1" role="dialog" aria-labelledby="exampleModalLongTitle" aria-hidden="true">
+  <div class="modal-dialog" role="document">
+    <div class="modal-content">
       <div class="modal-header">
         <button type="button" class="close" data-dismiss="modal" aria-label="Close">
           <span aria-hidden="true">&times;</span>
         </button>
-        <h4 class="modal-title" id="myLargeModalLabel">Large modal</h4>
+        <h5 class="modal-title" id="exampleModalLongTitle">Modal title</h5>
       </div>
       <div class="modal-body">
         ...
       </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
+        <button type="button" class="btn btn-primary">Save changes</button>
+      </div>
     </div>
   </div>
 </div>
+{% endhighlight %}
 
-<div class="modal fade bd-example-modal-sm" tabindex="-1" role="dialog" aria-labelledby="mySmallModalLabel" aria-hidden="true">
-  <div class="modal-dialog modal-sm">
-    <div class="modal-content">
+### Tooltips and popovers
 
+[Tooltips]({{ site.baseurl }}/components/tooltips/) and [popovers]({{ site.baseurl }}/components/popovers/) can be placed within modals as needed. When modals are closed, any tooltips and popovers within are also automatically dismissed.
+
+<div id="exampleModalPopovers" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="exampleModalPopoversLabel" aria-hidden="true">
+  <div class="modal-dialog" role="document">
+    <div class="modal-content">
       <div class="modal-header">
         <button type="button" class="close" data-dismiss="modal" aria-label="Close">
           <span aria-hidden="true">&times;</span>
         </button>
-        <h4 class="modal-title" id="mySmallModalLabel">Small modal</h4>
+        <h5 class="modal-title" id="exampleModalPopoversLabel">Modal title</h5>
       </div>
       <div class="modal-body">
-        ...
+        <h5>Popover in a modal</h5>
+        <p>This <a href="#" role="button" class="btn btn-secondary popover-test" title="Popover title" data-content="Popover body content is set in this attribute.">button</a> triggers a popover on click.</p>
+        <hr>
+        <h5>Tooltips in a modal</h5>
+        <p><a href="#" class="tooltip-test" title="Tooltip">This link</a> and <a href="#" class="tooltip-test" title="Tooltip">that link</a> have tooltips on hover.</p>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
+        <button type="button" class="btn btn-primary">Save changes</button>
       </div>
     </div>
   </div>
 </div>
 
-## Remove animation
-
-For modals that simply appear rather than fade in to view, remove the `.fade` class from your modal markup.
+<div class="bd-example">
+  <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalPopovers">
+    Launch demo modal
+  </button>
+</div>
 
 {% highlight html %}
-<div class="modal" tabindex="-1" role="dialog" aria-labelledby="..." aria-hidden="true">
-  ...
+<div class="modal-body">
+  <h5>Popover in a modal</h5>
+  <p>This <a href="#" role="button" class="btn btn-secondary popover-test" title="Popover title" data-content="Popover body content is set in this attribute.">button</a> triggers a popover on click.</p>
+  <hr>
+  <h5>Tooltips in a modal</h5>
+  <p><a href="#" class="tooltip-test" title="Tooltip">This link</a> and <a href="#" class="tooltip-test" title="Tooltip">that link</a> have tooltips on hover.</p>
 </div>
 {% endhighlight %}
 
-## Using the grid system
+### Using the grid
 
-To take advantage of the Bootstrap grid system within a modal, just nest `.container-fluid` within the `.modal-body` and then use the normal grid system classes within this container.
+Utilize the Bootstrap grid system within a modal by nesting `.container-fluid` within the `.modal-body`. Then, use the normal grid system classes as you would anywhere else.
 
-{% example html %}
 <div id="gridSystemModal" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="gridModalLabel" aria-hidden="true">
   <div class="modal-dialog" role="document">
     <div class="modal-content">
       <div class="modal-header">
         <button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
-        <h4 class="modal-title" id="gridModalLabel">Modal title</h4>
+        <h5 class="modal-title" id="gridModalLabel">Grids in modals</h5>
       </div>
       <div class="modal-body">
         <div class="container-fluid bd-example-row">
@@ -304,47 +307,79 @@ To take advantage of the Bootstrap grid system within a modal, just nest `.conta
     </div>
   </div>
 </div>
-<div class="bd-example bd-example-padded-bottom">
-  <button type="button" class="btn btn-primary btn-lg" data-toggle="modal" data-target="#gridSystemModal">
-    Launch demo modal
-  </button>
+
+<div class="bd-example">
+<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#gridSystemModal">
+  Launch demo modal
+</button>
 </div>
-{% endexample %}
 
-## Varying modal content based on trigger button
+{% highlight html %}
+<div class="modal-body">
+  <div class="container-fluid">
+    <div class="row">
+      <div class="col-md-4">.col-md-4</div>
+      <div class="col-md-4 col-md-offset-4">.col-md-4 .col-md-offset-4</div>
+    </div>
+    <div class="row">
+      <div class="col-md-3 col-md-offset-3">.col-md-3 .col-md-offset-3</div>
+      <div class="col-md-2 col-md-offset-4">.col-md-2 .col-md-offset-4</div>
+    </div>
+    <div class="row">
+      <div class="col-md-6 col-md-offset-3">.col-md-6 .col-md-offset-3</div>
+    </div>
+    <div class="row">
+      <div class="col-sm-9">
+        Level 1: .col-sm-9
+        <div class="row">
+          <div class="col-8 col-sm-6">
+            Level 2: .col-8 .col-sm-6
+          </div>
+          <div class="col-4 col-sm-6">
+            Level 2: .col-4 .col-sm-6
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+{% endhighlight %}
+
+### Varying modal content
+
+Have a bunch of buttons that all trigger the same modal with slightly different contents? Use `event.relatedTarget` and [HTML `data-*` attributes](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_data_attributes) (possibly [via jQuery](https://api.jquery.com/data/)) to vary the contents of the modal depending on which button was clicked.
 
-Have a bunch of buttons that all trigger the same modal, just with slightly different contents? Use `event.relatedTarget` and [HTML `data-*` attributes](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_data_attributes) (possibly [via jQuery](https://api.jquery.com/data/)) to vary the contents of the modal depending on which button was clicked. See the Modal Events docs for details on `relatedTarget`.
+Below is a live demo followed by example HTML and JavaScript. For more information, [read the modal events docs](#events) for details on `relatedTarget`.
 
 {% example html %}
-<div class="bd-example">
-  <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@mdo">Open modal for @mdo</button>
-  <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@fat">Open modal for @fat</button>
-  <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@getbootstrap">Open modal for @getbootstrap</button>
-  <div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
-    <div class="modal-dialog" role="document">
-      <div class="modal-content">
-        <div class="modal-header">
-          <button type="button" class="close" data-dismiss="modal" aria-label="Close">
-            <span aria-hidden="true">&times;</span>
-          </button>
-          <h4 class="modal-title" id="exampleModalLabel">New message</h4>
-        </div>
-        <div class="modal-body">
-          <form>
-            <div class="form-group">
-              <label for="recipient-name" class="form-control-label">Recipient:</label>
-              <input type="text" class="form-control" id="recipient-name">
-            </div>
-            <div class="form-group">
-              <label for="message-text" class="form-control-label">Message:</label>
-              <textarea class="form-control" id="message-text"></textarea>
-            </div>
-          </form>
-        </div>
-        <div class="modal-footer">
-          <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
-          <button type="button" class="btn btn-primary">Send message</button>
-        </div>
+<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@mdo">Open modal for @mdo</button>
+<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@fat">Open modal for @fat</button>
+<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@getbootstrap">Open modal for @getbootstrap</button>
+
+<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
+  <div class="modal-dialog" role="document">
+    <div class="modal-content">
+      <div class="modal-header">
+        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
+          <span aria-hidden="true">&times;</span>
+        </button>
+        <h5 class="modal-title" id="exampleModalLabel">New message</h5>
+      </div>
+      <div class="modal-body">
+        <form>
+          <div class="form-group">
+            <label for="recipient-name" class="form-control-label">Recipient:</label>
+            <input type="text" class="form-control" id="recipient-name">
+          </div>
+          <div class="form-group">
+            <label for="message-text" class="form-control-label">Message:</label>
+            <textarea class="form-control" id="message-text"></textarea>
+          </div>
+        </form>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
+        <button type="button" class="btn btn-primary">Send message</button>
       </div>
     </div>
   </div>
@@ -363,10 +398,95 @@ $('#exampleModal').on('show.bs.modal', function (event) {
 })
 {% endhighlight %}
 
-## Modals with dynamic heights
+### Remove animation
+
+For modals that simply appear rather than fade in to view, remove the `.fade` class from your modal markup.
+
+{% highlight html %}
+<div class="modal" tabindex="-1" role="dialog" aria-labelledby="..." aria-hidden="true">
+  ...
+</div>
+{% endhighlight %}
+
+### Dynamic heights
 
 If the height of a modal changes while it is open, you should call `$('#myModal').data('bs.modal').handleUpdate()` to readjust the modal's position in case a scrollbar appears.
 
+### Accessibility
+
+Be sure to add `role="dialog"` and `aria-labelledby="..."`, referencing the modal title, to `.modal`, and `role="document"` to the `.modal-dialog` itself. Additionally, you may give a description of your modal dialog with `aria-describedby` on `.modal`.
+
+### Embedding YouTube videos
+
+Embedding YouTube videos in modals requires additional JavaScript not in Bootstrap to automatically stop playback and more. [See this helpful Stack Overflow post](https://stackoverflow.com/questions/18622508/bootstrap-3-and-youtube-in-modal) for more information.
+
+## Optional sizes
+
+Modals have two optional sizes, available via modifier classes to be placed on a `.modal-dialog`. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports.
+
+<div class="bd-example">
+  <button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-lg">Large modal</button>
+  <button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-sm">Small modal</button>
+</div>
+
+{% highlight html %}
+<!-- Large modal -->
+<button class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-lg">Large modal</button>
+
+<div class="modal fade bd-example-modal-lg" tabindex="-1" role="dialog" aria-labelledby="myLargeModalLabel" aria-hidden="true">
+  <div class="modal-dialog modal-lg">
+    <div class="modal-content">
+      ...
+    </div>
+  </div>
+</div>
+
+<!-- Small modal -->
+<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-sm">Small modal</button>
+
+<div class="modal fade bd-example-modal-sm" tabindex="-1" role="dialog" aria-labelledby="mySmallModalLabel" aria-hidden="true">
+  <div class="modal-dialog modal-sm">
+    <div class="modal-content">
+      ...
+    </div>
+  </div>
+</div>
+{% endhighlight %}
+
+<div class="modal fade bd-example-modal-lg" tabindex="-1" role="dialog" aria-labelledby="myLargeModalLabel" aria-hidden="true">
+  <div class="modal-dialog modal-lg">
+    <div class="modal-content">
+
+      <div class="modal-header">
+        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
+          <span aria-hidden="true">&times;</span>
+        </button>
+        <h4 class="modal-title" id="myLargeModalLabel">Large modal</h4>
+      </div>
+      <div class="modal-body">
+        ...
+      </div>
+    </div>
+  </div>
+</div>
+
+<div class="modal fade bd-example-modal-sm" tabindex="-1" role="dialog" aria-labelledby="mySmallModalLabel" aria-hidden="true">
+  <div class="modal-dialog modal-sm">
+    <div class="modal-content">
+
+      <div class="modal-header">
+        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
+          <span aria-hidden="true">&times;</span>
+        </button>
+        <h4 class="modal-title" id="mySmallModalLabel">Small modal</h4>
+      </div>
+      <div class="modal-body">
+        ...
+      </div>
+    </div>
+  </div>
+</div>
+
 ## Usage
 
 The modal plugin toggles your hidden content on demand, via data attributes or JavaScript. It also adds `.modal-open` to the `<body>` to override default scrolling behavior and generates a `.modal-backdrop` to provide a click area for dismissing shown modals when clicking outside the modal.

From 82664a234f384b20b6530201bc04052efd4b6153 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 24 Dec 2016 14:09:06 -0800
Subject: [PATCH 28/29] dedupe

---
 docs/components/modal.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/components/modal.md b/docs/components/modal.md
index 7251c384287d..23551efa35dc 100644
--- a/docs/components/modal.md
+++ b/docs/components/modal.md
@@ -88,14 +88,14 @@ Below is a _static_ modal example (meaning its `position` and `display` have bee
 
 Toggle a working modal demo by clicking the button below. It will slide down and fade in from the top of the page.
 
-<div id="exampleModal" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
+<div id="exampleModalLive" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="exampleModalLiveLabel" aria-hidden="true">
   <div class="modal-dialog" role="document">
     <div class="modal-content">
       <div class="modal-header">
         <button type="button" class="close" data-dismiss="modal" aria-label="Close">
           <span aria-hidden="true">&times;</span>
         </button>
-        <h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
+        <h5 class="modal-title" id="exampleModalLiveLabel">Modal title</h5>
       </div>
       <div class="modal-body">
         <p>Woohoo, you're reading this text in a modal!</p>
@@ -109,7 +109,7 @@ Toggle a working modal demo by clicking the button below. It will slide down and
 </div>
 
 <div class="bd-example">
-  <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
+  <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalLive">
     Launch demo modal
   </button>
 </div>

From 2a2d1b9ba36e45e1af7bf7991b513381527bb4d7 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 24 Dec 2016 14:11:03 -0800
Subject: [PATCH 29/29] fixes #21423 by updating docs to mention flex display
 instead of inline-block; clarifies follow-up text about use of the proper
 utilities

---
 docs/components/forms.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/components/forms.md b/docs/components/forms.md
index f40d79fcef06..bbf55eda896b 100644
--- a/docs/components/forms.md
+++ b/docs/components/forms.md
@@ -275,7 +275,7 @@ The `.form-group` class is the easiest way to add some structure to forms. Its o
 
 Use the `.form-inline` class to display a series of labels, form controls, and buttons on a single horizontal row. Form controls within inline forms vary slightly from their default states.
 
-- Controls are `display: inline-block` (or `flex` when enabled) to provide alignment control via `vertical-align` and `margin`. Those also means you'll have some HTML character spaces between elements by default.
+- Controls are `display: flex`, collapsing any HTML white space and allowing you to provide alignment control with [spacing]({{ site.baseurl }}/utilities/spacing/) and [flexbox]({{ site.baseurl }}/utilities/flexbox/) utilities.
 - Controls and input groups receive `width: auto` to override the Bootstrap default `width: 100%`.
 - Controls **only appear inline in viewports that are at least 576px wide** to account for narrow viewports on mobile devices.