Skip to content
GitLab
Commit 9979827c authored by Mark Otto's avatar Mark Otto Committed by Mark Otto
Browse files

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.
parent d9baeeb0
11 merge requests!28721Hot test,!27561Adds font-weight-medium to font weight classes,!26437merge,!22391V4 dev,!22547Finished a new translation for bootstrap,!22143Fix selectable disabled toggle radio buttons,!22598test,!25326Adjust examples,!23995Add back cursor: pointer for .btn-link,!23178Spinner,!17021v4
Hide whitespace changes
Inline Side-by-side
Showing
with 75 additions and 92 deletions
+75 -92
docs/components/navs.md
+ 75
- 92
View file @ 9979827c
......@@ -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>
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment