Merge pull request #19890 from twbs/v4-navbars

v4: Navbar improvements

3 files changed, 229 insertions, 33 deletions

diff --git a/docs/components/navbar.md b/docs/components/navbar.md
index 49ca8533d..bb819ff9e 100644
--- a/docs/components/navbar.md
+++ b/docs/components/navbar.md
@@ -5,7 +5,7 @@ description: Documentation and examples for Bootstrap's powerful, responsive nav
 group: components
 ---
 
-The navbar is a simple wrapper for positioning branding, navigation, and other elements into a concise navigation header. It's easily extensible and, with the help of our collapse plugin, it can easily integrate offscreen content.
+The navbar is a wrapper that positions branding, navigation, and other elements into a concise header. It's easily extensible and thanks to our Collapse plugin, it can easily integrate responsive behaviors.
 
 ## Contents
 
@@ -18,18 +18,20 @@ Here's what you need to know before getting started with the navbar:
 
 - Navbars require a wrapping `.navbar` and a [color scheme](#color-schemes).
 - Navbars and their contents are fluid by default. Use [optional containers](#containers) to limit their horizontal width.
-- Use `.pull-*-left` and `.pull-*-right` to quickly align sub-components.
+- Use `.float-*-left` and `.float-*-right` to quickly align sub-components.
 - Ensure accessibility by using a `<nav>` element or, if using a more generic element such as a `<div>`, add a `role="navigation"` to every navbar to explicitly identify it as a landmark region for users of assistive technologies.
 
 ## Supported content
 
-Navbars come with built-in support for a handful of sub-components. Mix and match from the following as you need:
+Navbars come with built-in support for a handful of sub-components. Mix and match from the following as needed:
 
 - `.navbar-brand` for your company, product, or project name
 - `.navbar-nav` for a full-height and lightweight navigation (including support for dropdowns)
 - `.navbar-toggler` for use with our collapse plugin and other [navigation toggling](#collapsible-content) behaviors.
+- Inline forms with `.float-` utilities for form controls and components.
+- `.navbar-text` for adding vertically centered strings of text.
 
-Here's an example of all the sub-components included in a default, light navbar:
+Here's an example of all the sub-components included in a default, non-responsive light themed navbar. [See the responsive examples](#collapsible-content) for collapsing nav support.
 
 {% example html %}
 <nav class="navbar navbar-light bg-faded">
@@ -39,13 +41,18 @@ Here's an example of all the sub-components included in a default, light navbar:
       <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
     </li>
     <li class="nav-item">
-      <a class="nav-link" href="#">Features</a>
+      <a class="nav-link" href="#">Link</a>
     </li>
     <li class="nav-item">
-      <a class="nav-link" href="#">Pricing</a>
+      <a class="nav-link" href="#">Link</a>
     </li>
-    <li class="nav-item">
-      <a class="nav-link" href="#">About</a>
+    <li class="nav-item dropdown">
+      <a class="nav-link dropdown-toggle" href="http://example.com" id="supportedContentDropdown" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown</a>
+      <div class="dropdown-menu" aria-labelledby="supportedContentDropdown">
+        <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 float-xs-right">
@@ -60,20 +67,44 @@ Here's an example of all the sub-components included in a default, light navbar:
 The `.navbar-brand` can be applied to most elements, but an anchor works best as some elements might require utility classes or custom styles.
 
 {% example html %}
+<!-- As a link -->
 <nav class="navbar navbar-light bg-faded">
   <a class="navbar-brand" href="#">Navbar</a>
 </nav>
 
+<!-- As a heading -->
 <nav class="navbar navbar-light bg-faded">
   <h1 class="navbar-brand mb-0">Navbar</h1>
 </nav>
+{% endexample %}
+
+Adding images to the `.navbar-brand` will likely always require custom styles or utilities to properly size. Here are some examples to demonstrate.
 
+{% example html %}
+<!-- Just an image -->
+<nav class="navbar navbar-light bg-faded">
+  <a class="navbar-brand" href="#">
+    <img src="{{ site.baseurl }}/assets/brand/bootstrap-solid.svg" width="30" height="30" alt="">
+  </a>
+</nav>
+{% endexample %}
+
+{% example html %}
+<!-- Image and text -->
+<nav class="navbar navbar-light bg-faded">
+  <a class="navbar-brand" href="#">
+    <img src="{{ site.baseurl }}/assets/brand/bootstrap-solid.svg" width="30" height="30" class="d-inline-block align-top" alt="">
+    Bootstrap
+  </a>
+</nav>
 {% endexample %}
 
 ### Nav
 
 Navbar navigation is similar to our regular nav options—use the `.nav` base class with a modifier to achieve a particular look. In this case you'll want `.nav.navbar-nav`.
 
+Active states—with `.active`—to indicate the current page can be applied directly to `.nav-link`s or their immediate parent `.nav-item`s.
+
 {% example html %}
 <nav class="navbar navbar-light bg-faded">
   <ul class="nav navbar-nav">
@@ -106,6 +137,103 @@ And because we use classes for our navs, you can avoid the list-based approach e
 </nav>
 {% endexample %}
 
+You may also utilize dropdowns in your navbar nav. Dropdown menus require a wrapping element for positioning, so be sure to use separate and nested elements for `.nav-item` and `.nav-link` as shown below.
+
+{% example html %}
+<nav class="navbar navbar-light bg-faded">
+  <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="#">Features</a>
+    </li>
+    <li class="nav-item">
+      <a class="nav-link" href="#">Pricing</a>
+    </li>
+    <li class="nav-item dropdown">
+      <a class="nav-link dropdown-toggle" href="http://example.com" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+        Dropdown link
+      </a>
+      <div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
+        <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>
+</nav>
+{% endexample %}
+
+### Forms
+
+Place various form controls and components within a navbar with `.form-inline`. Align them with `.float-` utilities as needed.
+
+{% example html %}
+<nav class="navbar navbar-light bg-faded">
+  <form class="form-inline float-xs-left">
+    <input class="form-control" type="text" placeholder="Search">
+    <button class="btn btn-outline-success" type="submit">Search</button>
+  </form>
+</nav>
+{% endexample %}
+
+Input groups work, too:
+
+{% example html %}
+<nav class="navbar navbar-light bg-faded">
+  <form class="form-inline float-xs-left">
+    <div class="input-group">
+      <span class="input-group-addon" id="basic-addon1">@</span>
+      <input type="text" class="form-control" placeholder="Username" aria-describedby="basic-addon1">
+    </div>
+  </form>
+</nav>
+{% endexample %}
+
+Various buttons are supported as part of these navbar forms, too. This is also a great reminder that vertical alignment utilites can be used to align different sized elements.
+
+{% example html %}
+<nav class="navbar navbar-light bg-faded">
+  <form class="form-inline float-xs-left">
+    <button class="btn btn-outline-success" type="button">Main button</button>
+    <button class="btn btn-sm align-middle btn-outline-secondary" type="button">Smaller button</button>
+  </form>
+</nav>
+{% endexample %}
+
+### Text
+
+Navbars may contain bits of text with the help of `.navbar-text`. This class adjusts vertical alignment and horizontal spacing for strings of text.
+
+{% example html %}
+<nav class="navbar navbar-light bg-faded">
+  <span class="navbar-text">
+    Navbar text with an inline element
+  </span>
+</nav>
+{% endexample %}
+
+Using our utility classes, you can change the alignment and appearance of your navbar text.
+
+{% example html %}
+<nav class="navbar navbar-light bg-faded">
+  <span class="navbar-text float-xs-right text-muted">
+    Muted navbar text that's floated right
+  </span>
+</nav>
+{% endexample %}
+
+Similarly, you can use utility classes to align navbar text to other navbar elements like the brand and navigation (which are automatically floated already).
+
+{% example html %}
+<nav class="navbar navbar-light bg-faded">
+  <a class="navbar-brand" href="#">Navbar</a>
+  <span class="navbar-text float-xs-left">
+    Navbar text that's floated left
+  </span>
+</nav>
+{% endexample %}
 
 ## Color schemes
 
@@ -244,7 +372,7 @@ Our collapse plugin allows you to use a `<button>` or `<a>` to toggle hidden con
 <nav class="navbar navbar-light bg-faded">
   <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#exCollapsingNavbar" aria-controls="exCollapsingNavbar" aria-expanded="false" aria-label="Toggle navigation"></button>
   <div class="collapse" id="exCollapsingNavbar">
-    <div class="bg-inverse p-1">
+    <div class="bg-inverse text-muted p-1">
       <h4>Collapsed content</h4>
       <span class="text-muted">Toggleable via the navbar brand.</span>
     </div>
@@ -256,23 +384,32 @@ For more complex navbar patterns, like those used in Bootstrap v3, use the `.nav
 
 {% example html %}
 <nav class="navbar navbar-light bg-faded">
-  <button class="navbar-toggler hidden-sm-up" type="button" data-toggle="collapse" data-target="#exCollapsingNavbar2" aria-controls="exCollapsingNavbar2" aria-expanded="false" aria-label="Toggle navigation"></button>
-  <div class="collapse navbar-toggleable-xs" id="exCollapsingNavbar2">
-    <a class="navbar-brand" href="#">Responsive navbar</a>
+  <button class="navbar-toggler hidden-lg-up" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation"></button>
+  <div class="collapse navbar-toggleable-md" id="navbarResponsive">
+    <a class="navbar-brand" href="#">Navbar</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="#">Features</a>
+        <a class="nav-link" href="#">Link</a>
       </li>
       <li class="nav-item">
-        <a class="nav-link" href="#">Pricing</a>
+        <a class="nav-link" href="#">Link</a>
       </li>
-      <li class="nav-item">
-        <a class="nav-link" href="#">About</a>
+      <li class="nav-item dropdown">
+        <a class="nav-link dropdown-toggle" href="http://example.com" id="responsiveNavbarDropdown" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown</a>
+        <div class="dropdown-menu" aria-labelledby="responsiveNavbarDropdown">
+          <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 float-lg-right">
+      <input class="form-control" type="text" placeholder="Search">
+      <button class="btn btn-outline-success" type="submit">Search</button>
+    </form>
   </div>
 </nav>
 {% endexample %}
diff --git a/scss/_navbar.scss b/scss/_navbar.scss
index c91e830bd..7dc2a2b0d 100644
--- a/scss/_navbar.scss
+++ b/scss/_navbar.scss
@@ -69,26 +69,23 @@
 
 .navbar-brand {
   float: left;
-  padding-top:    $navbar-brand-padding-y;
+  padding-top: $navbar-brand-padding-y;
   padding-bottom: $navbar-brand-padding-y;
   margin-right: 1rem;
   font-size: $font-size-lg;
+  line-height: inherit;
 
   @include hover-focus {
     text-decoration: none;
   }
-
-  > img {
-    display: block;
-  }
 }
 
 
 .navbar-divider {
   float: left;
   width: $border-width;
-  padding-top: .425rem;
-  padding-bottom: .425rem;
+  padding-top: $navbar-divider-padding-y;
+  padding-bottom: $navbar-divider-padding-y;
   margin-right: $navbar-padding-x;
   margin-left:  $navbar-padding-x;
   overflow: hidden;
@@ -99,6 +96,17 @@
 }
 
 
+// Navbar text
+//
+//
+
+.navbar-text {
+  display: inline-block;
+  padding-top:    .425rem;
+  padding-bottom: .425rem;
+}
+
+
 // Navbar toggle
 //
 // Custom button for toggling the `.navbar-collapse`, powered by the collapse
@@ -107,19 +115,55 @@
 .navbar-toggler {
   width: 2.5em;
   height: 2em;
-  padding: .5rem .75rem;
-  font-size: $font-size-lg;
+  padding: $navbar-toggler-padding-y $navbar-toggler-padding-x;
+  font-size: $navbar-toggler-font-size;
   line-height: 1;
   background: transparent no-repeat center center;
   background-size: 24px 24px;
   border: $border-width solid transparent;
-  @include border-radius($btn-border-radius);
+  @include border-radius($navbar-toggler-border-radius);
 
   @include hover-focus {
     text-decoration: none;
   }
 }
 
+// scss-lint:disable ImportantRule
+.navbar-toggleable {
+  @each $breakpoint in map-keys($grid-breakpoints) {
+    $next: breakpoint-next($breakpoint, $grid-breakpoints);
+
+    &-#{$breakpoint} {
+      @include clearfix;
+
+      @include media-breakpoint-down($breakpoint) {
+        .navbar-brand {
+          display: block;
+          float: none;
+          margin-top: .5rem;
+          margin-right: 0;
+        }
+
+        .navbar-nav {
+          margin-top: .5rem;
+          margin-bottom: .5rem;
+
+          .dropdown-menu {
+            position: static;
+            float: none;
+          }
+        }
+      }
+
+      @include media-breakpoint-up($next) {
+        display: block;
+      }
+    }
+  }
+}
+// scss-lint:enable ImportantRule
+
+
 // Navigation
 //
 // Custom navbar navigation built on the base `.nav` styles.
@@ -146,7 +190,8 @@
 
 // Dark links against a light background
 .navbar-light {
-  .navbar-brand {
+  .navbar-brand,
+  .navbar-toggler {
     color: $navbar-light-active-color;
 
     @include hover-focus {
@@ -175,6 +220,7 @@
 
   .navbar-toggler {
     background-image: $navbar-light-toggler-bg;
+    border-color: $navbar-light-toggler-border;
   }
 
   .navbar-divider {
@@ -184,7 +230,8 @@
 
 // White links against a dark background
 .navbar-dark {
-  .navbar-brand {
+  .navbar-brand,
+  .navbar-toggler {
     color: $navbar-dark-active-color;
 
     @include hover-focus {
@@ -213,6 +260,7 @@
 
   .navbar-toggler {
     background-image: $navbar-dark-toggler-bg;
+    border-color: $navbar-dark-toggler-border;
   }
 
   .navbar-divider {
diff --git a/scss/_variables.scss b/scss/_variables.scss
index b5ca86f3d..13432f2f3 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -495,20 +495,31 @@ $zindex-modal:             1050 !default;
 $navbar-border-radius:              $border-radius !default;
 $navbar-padding-x:                  $spacer !default;
 $navbar-padding-y:                  ($spacer / 2) !default;
+
 $navbar-brand-padding-y:            .25rem !default;
 
+$navbar-divider-padding-y:          .425rem !default;
+
+$navbar-toggler-padding-x:           .75rem !default;
+$navbar-toggler-padding-y:           .5rem !default;
+$navbar-toggler-font-size:           $font-size-lg !default;
+$navbar-toggler-border-radius:       $btn-border-radius !default;
+$navbar-toggler-padding-x:           .75rem !default;
+$navbar-toggler-padding-y:           .5rem !default;
+
 $navbar-dark-color:                 rgba(255,255,255,.5) !default;
 $navbar-dark-hover-color:           rgba(255,255,255,.75) !default;
 $navbar-dark-active-color:          rgba(255,255,255,1) !default;
 $navbar-dark-disabled-color:        rgba(255,255,255,.25) !default;
 $navbar-dark-toggler-bg: url("data:image/svg+xml;charset=utf8,%3Csvg viewBox='0 0 32 32' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath stroke='#{$navbar-dark-color}' stroke-width='2' stroke-linecap='round' stroke-miterlimit='10' d='M4 8h24M4 16h24M4 24h24'/%3E%3C/svg%3E") !default;
+$navbar-dark-toggler-border:        rgba(255,255,255,.1) !default;
 
-$navbar-light-color:                rgba(0,0,0,.3) !default;
-$navbar-light-hover-color:          rgba(0,0,0,.6) !default;
-$navbar-light-active-color:         rgba(0,0,0,.8) !default;
-$navbar-light-disabled-color:       rgba(0,0,0,.15) !default;
+$navbar-light-color:                rgba(0,0,0,.5) !default;
+$navbar-light-hover-color:          rgba(0,0,0,.7) !default;
+$navbar-light-active-color:         rgba(0,0,0,.9) !default;
+$navbar-light-disabled-color:       rgba(0,0,0,.3) !default;
 $navbar-light-toggler-bg: url("data:image/svg+xml;charset=utf8,%3Csvg viewBox='0 0 32 32' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath stroke='#{$navbar-light-color}' stroke-width='2' stroke-linecap='round' stroke-miterlimit='10' d='M4 8h24M4 16h24M4 24h24'/%3E%3C/svg%3E") !default;
-
+$navbar-light-toggler-border:       rgba(0,0,0,.1) !default;
 
 // Navs