0
0
mirror of https://github.com/twbs/bootstrap.git synced 2024-12-01 13:24:25 +01:00

update components docs

This commit is contained in:
Mark Otto 2017-05-27 23:01:14 -07:00
parent 5a3a356651
commit c72cc98bd5
21 changed files with 69 additions and 168 deletions

View File

@ -3,15 +3,9 @@ layout: docs
title: Alerts
description: Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages.
group: components
toc: true
---
Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Examples
Alerts are available for any length of text, as well as an optional dismiss button. For proper styling, use one of the four **required** contextual classes (e.g., `.alert-success`). For inline dismissal, use the [alerts jQuery plugin](#dismissing).

View File

@ -3,27 +3,30 @@ layout: docs
title: Badges
description: Documentation and examples for badges, our small count and labeling component.
group: components
toc: true
---
Small and adaptive tag for adding context to just about any content.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Example
Badges scale to match the size of the immediate parent element by using relative font sizing and `em` units.
{% example html %}
<div class="bd-example">
<div class="h1">Example heading <span class="badge badge-default">New</span></div>
<div class="h2">Example heading <span class="badge badge-default">New</span></div>
<div class="h3">Example heading <span class="badge badge-default">New</span></div>
<div class="h4">Example heading <span class="badge badge-default">New</span></div>
<div class="h5">Example heading <span class="badge badge-default">New</span></div>
<div class="h6">Example heading <span class="badge badge-default">New</span></div>
</div>
{% highlight html %}
<h1>Example heading <span class="badge badge-default">New</span></h1>
<h2>Example heading <span class="badge badge-default">New</span></h2>
<h3>Example heading <span class="badge badge-default">New</span></h3>
<h4>Example heading <span class="badge badge-default">New</span></h4>
<h5>Example heading <span class="badge badge-default">New</span></h5>
<h6>Example heading <span class="badge badge-default">New</span></h6>
{% endexample %}
{% endhighlight %}
## Contextual variations

View File

@ -1,11 +1,11 @@
---
layout: docs
title: Breadcrumb
description: Indicate the current page's location within a navigational hierarchy.
description: Indicate the current page's location within a navigational hierarchy that automatically adds separators via CSS.
group: components
---
Indicate the current page's location within a navigational hierarchy. Separators are automatically added in CSS through [`::before`](https://developer.mozilla.org/en-US/docs/Web/CSS/::before) and [`content`](https://developer.mozilla.org/en-US/docs/Web/CSS/content).
Separators are automatically added in CSS through [`::before`](https://developer.mozilla.org/en-US/docs/Web/CSS/::before) and [`content`](https://developer.mozilla.org/en-US/docs/Web/CSS/content).
{% example html %}
<ol class="breadcrumb">

View File

@ -3,26 +3,12 @@ layout: docs
title: Button group
description: Group a series of buttons together on a single line with the button group, and super-power them with JavaScript.
group: components
toc: true
---
Group a series of buttons together on a single line with the button group. Add on optional JavaScript radio and checkbox style behavior with [our buttons plugin]({{ site.baseurl }}/components/buttons/#button-plugin).
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
{% callout warning %}
## Ensure correct `role` and provide a label
In order for assistive technologies (such as screen readers) to convey that a series of buttons is grouped, an appropriate `role` attribute needs to be provided. For button groups, this would be `role="group"`, while toolbars should have a `role="toolbar"`.
In addition, groups and toolbars should be given an explicit label, as most assistive technologies will otherwise not announce them, despite the presence of the correct role attribute. In the examples provided here, we use `aria-label`, but alternatives such as `aria-labelledby` can also be used.
{% endcallout %}
## Basic example
Wrap a series of buttons with `.btn` in `.btn-group`.
Wrap a series of buttons with `.btn` in `.btn-group`. Add on optional JavaScript radio and checkbox style behavior with [our buttons plugin]({{ site.baseurl }}/components/buttons/#button-plugin).
{% example html %}
<div class="btn-group" role="group" aria-label="Basic example">
@ -32,6 +18,13 @@ Wrap a series of buttons with `.btn` in `.btn-group`.
</div>
{% endexample %}
{% callout warning %}
#### Ensure correct `role` and provide a label
In order for assistive technologies (such as screen readers) to convey that a series of buttons is grouped, an appropriate `role` attribute needs to be provided. For button groups, this would be `role="group"`, while toolbars should have a `role="toolbar"`.
In addition, groups and toolbars should be given an explicit label, as most assistive technologies will otherwise not announce them, despite the presence of the correct role attribute. In the examples provided here, we use `aria-label`, but alternatives such as `aria-labelledby` can also be used.
{% endcallout %}
## Button toolbar
Combine sets of button groups into button toolbars for more complex components. Use utility classes as needed to space out groups, buttons, and more.

View File

@ -4,15 +4,9 @@ title: Buttons
description: Use Bootstrap's custom button styles for actions in forms, dialogs, and more with support for multiple sizes, states, and more.
group: components
redirect_from: "/components/"
toc: true
---
Use Bootstrap's custom button styles for actions in forms, dialogs, and more. Includes support for a handful of contextual variations, sizes, states, and more.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Examples
Bootstrap includes six predefined button styles, each serving its own semantic purpose.

View File

@ -3,17 +3,15 @@ layout: docs
title: Cards
description: Bootstrap's cards provide a flexible and extensible content container with multiple variants and options.
group: components
toc: true
---
## About
A **card** is a flexible and extensible content container. It includes options for headers and footers, a wide variety of content, contextual background colors, and powerful display options.
If you're familiar with Bootstrap 3, cards replace our old panels, wells, and thumbnails. Similar functionality to those components is available as modifier classes for cards.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Example
Cards are built with as little markup and styles as possible, but still manage to deliver a ton of control and customization. Built with flexbox, they offer easy alignment and mix well with other Bootstrap components.

View File

@ -3,19 +3,17 @@ layout: docs
title: Carousel
description: A slideshow component for cycling through elements—images or slides of text—like a carousel.
group: components
toc: true
---
## How it works
The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators.
In browsers where the [Page Visibility API](https://www.w3.org/TR/page-visibility/) is supported, the carousel will avoid sliding when the webpage is not visible to the user (such as when the browser tab is inactive, the browser window is minimized, etc.).
Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Example
Carousels don't automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. While carousels support previous/next controls and indicators, they're not explicitly required. Add and customize as you see fit.

View File

@ -3,15 +3,9 @@ layout: docs
title: Collapse
description: Toggle the visibility of content across your project with a few classes and our JavaScript plugins.
group: components
toc: true
---
The Bootstrap collapse plugin allows you to toggle content on your pages with a few classes thanks to some helpful JavaScript.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Example
Click the buttons below to show and hide another element via class changes:

View File

@ -3,18 +3,14 @@ layout: docs
title: Dropdowns
description: Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin.
group: components
toc: true
---
Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They're made interactive with the included Bootstrap dropdown JavaScript plugin. They're toggled by clicking, not by hovering; this is [an intentional design decision.](http://markdotto.com/2012/02/27/bootstrap-explained-dropdowns/)
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Overview
Things to know when using the popover plugin:
Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They're made interactive with the included Bootstrap dropdown JavaScript plugin. They're toggled by clicking, not by hovering; this is [an intentional design decision.](http://markdotto.com/2012/02/27/bootstrap-explained-dropdowns/)
Things to know when using the dropdown plugin:
- Dropdown rely on the 3rd party library [Popper.js](https://popper.js.org) for positioning. You must include [popper.min.js](https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.9.9/umd/popper.min.js) before bootstrap.js in order for dropdowns to work!
- Popper.js handle natively the flip of Dropdown when it's outside the viewport, if you want to disable that's behavior use `flip` attribute

View File

@ -1,17 +1,11 @@
---
layout: docs
title: Forms
description: Examples and usage guidelines for form controls, form layouts, and custom forms.
description: Examples and usage guidelines for form control styles, layout options, and custom components for creating a wide variety of forms.
group: components
toc: true
---
Bootstrap provides several form control styles, layout options, and custom components for creating a wide variety of forms.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Form controls
Bootstrap's form controls expand on [our Rebooted form styles]({{ site.baseurl }}/content/reboot/#forms) with classes. Use these classes to opt into their customized displays for a more consistent rendering across browsers and devices. The example form below demonstrates common HTML form elements that receive updated styles from Bootstrap with additional classes.

View File

@ -1,17 +1,11 @@
---
layout: docs
title: Input group
description: Extend form controls with the input group.
description: Easily extend form controls by adding text, buttons, or button groups on either side of textual inputs.
group: components
toc: true
---
Easily extend form controls by adding text, buttons, or button groups on either side of textual `<input>`s.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Basic example
Place one add-on or button on either side of an input. You may also place one on both sides of an input. **We do not support multiple form-controls in a single input group.**

View File

@ -7,8 +7,6 @@ group: components
A lightweight, flexible component that can optionally extend the entire viewport to showcase key marketing messages on your site.
## Example
{% example html %}
<div class="jumbotron">
<h1 class="display-3">Hello, world!</h1>

View File

@ -1,18 +1,13 @@
---
layout: docs
title: List group
description: Learn about Bootstrap's list group component for rendering series of related content.
description: List groups are a flexible and powerful component for displaying a series of content. Modify and extend them to support just about any content within.
group: components
toc: true
---
List groups are a flexible and powerful component for displaying a series of content. List group items can be modified and extended to support just about any content within. They can also be used as navigation with the right modifier class.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Basic example
The most basic list group is an unordered list with list items and the proper classes. Build upon it with the options that follow, or with your own CSS as needed.
{% example html %}

View File

@ -1,17 +1,11 @@
---
layout: docs
title: Modal
description: Learn how to use Bootstrap's modals to add dialog prompts to your site.
description: Use Bootstrap's JavaScript modal plugin to add dialogs to your site for lightboxes, user notifications, or completely custom content.
group: components
toc: true
---
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}
## How it works
Before getting started with Bootstrap's modal component, be sure to read the following as our menu options have recently changed.

View File

@ -1,17 +1,11 @@
---
layout: docs
title: Navbar
description: Documentation and examples for Bootstrap's powerful, responsive navigation header.
description: Documentation and examples for Bootstrap's powerful, responsive navigation header, the navbar. Includes support for branding, navigation, and more, including support for our collapse plugin.
group: components
toc: true
---
The navbar is a wrapper that positions branding, navigation, and other elements in a concise header. It's easily extensible and, thanks to our Collapse plugin, can easily integrate responsive behaviors.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## How it works
Here's what you need to know before getting started with the navbar:
@ -76,7 +70,7 @@ The `.navbar-brand` can be applied to most elements, but an anchor works best as
<!-- As a heading -->
<nav class="navbar navbar-light bg-faded">
<h1 class="navbar-brand mb-0">Navbar</h1>
<span class="h1" class="navbar-brand mb-0">Navbar</span>
</nav>
{% endexample %}

View File

@ -3,17 +3,13 @@ layout: docs
title: Navs
description: Documentation and examples for how to use Bootstrap's included navigation components.
group: components
toc: true
---
Navigation available in Bootstrap share general markup and styles, from the base `.nav` class to the active and disabled states. Swap modifier classes to switch between each style.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Base nav
Navigation available in Bootstrap share general markup and styles, from the base `.nav` class to the active and disabled states. Swap modifier classes to switch between each style.
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.
{% callout info %}
@ -297,7 +293,7 @@ Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin
</ul>
{% endexample %}
## JavaScript behavior for dynamic tabbed interfaces
## JavaScript behavior
Use the tab JavaScript plugin—include it individually or through the compiled `bootstrap.js` file—to extend our navigational tabs and pills to create tabbable panes of local content, even via dropdown menus.

View File

@ -1,17 +1,11 @@
---
layout: docs
title: Pagination
description: Documentation and examples for showing pagination links.
description: Documentation and examples for showing pagination to indicate a series of related content exists across multiple pages.
group: components
toc: true
---
Pagination links indicate a series of related content exists across multiple pages. Typically these are used where a multi-page approach to long lists of content improves general performance, such as in search results or inboxes.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Overview
We use a large block of connected links for our pagination, making links hard to miss and easily scalable—all while providing large hit areas. Pagination is built with list HTML elements so screen readers can announce the number of available links. Use a wrapping `<nav>` element to identify it as a navigation section to screen readers and other assistive technologies.

View File

@ -1,17 +1,11 @@
---
layout: docs
title: Popovers
description: Documentation and examples for adding Bootstrap popovers to your site.
description: Documentation and examples for adding Bootstrap popovers, like those found in iOS, to any element on your site.
group: components
toc: true
---
Add small overlay content, like those found in iOS, to any element for housing secondary information.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Overview
Things to know when using the popover plugin:

View File

@ -1,20 +1,14 @@
---
layout: docs
title: Progress
description: Documentation and examples for using Bootstrap progress bars.
description: Documentation and examples for using Bootstrap custom progress bars featuring support for stacked bars, animated backgrounds, and text labels.
group: components
toc: true
---
Use our custom progress component for displaying simple or complex progress bars. We don't use [the HTML5 `<progress>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress), ensuring you can stack progress bars, animate them, and place text labels over them.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## How it works
Progress components are built with two HTML elements, some CSS to set the width, and a few attributes.
Progress components are built with two HTML elements, some CSS to set the width, and a few attributes. We don't use [the HTML5 `<progress>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress), ensuring you can stack progress bars, animate them, and place text labels over them.
- We use the `.progress` as a wrapper to indicate the max value of the progress bar.
- We use the inner `.progress-bar` to indicate the progress so far.
@ -49,11 +43,7 @@ Bootstrap provides a handful of [utilities for setting width]({{ site.baseurl }}
</div>
{% endexample %}
## Customizing
Customize the appearance of your progress bars with custom CSS, background utilities, stripes, and more.
### Labels
## Labels
Add labels to your progress bars by placing text within the `.progress-bar`.
@ -63,7 +53,7 @@ Add labels to your progress bars by placing text within the `.progress-bar`.
</div>
{% endexample %}
### Height
## Height
We only set a `height` value on the `.progress-bar`, so if you change that value the outer `.progress` will automatically resize accordingly.
@ -76,7 +66,7 @@ We only set a `height` value on the `.progress-bar`, so if you change that value
</div>
{% endexample %}
### Backgrounds
## Backgrounds
Use background utility classes to change the appearance of individual progress bars.
@ -95,7 +85,7 @@ Use background utility classes to change the appearance of individual progress b
</div>
{% endexample %}
### Multiple bars
## Multiple bars
Include multiple progress bars in a progress component if you need.
@ -107,7 +97,7 @@ Include multiple progress bars in a progress component if you need.
</div>
{% endexample %}
### Striped
## Striped
Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gradient over the progress bar's background color.
@ -129,7 +119,7 @@ Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gra
</div>
{% endexample %}
### Animated stripes
## Animated stripes
The striped gradient can also be animated. Add `.progress-bar-animated` to `.progress-bar` to animate the stripes right to left via CSS3 animations.

View File

@ -1,17 +1,11 @@
---
layout: docs
title: Scrollspy
description: Documentation and examples for the scrollspy plugin with Bootstrap's navigation components.
description: Automatically update Bootstrap navigation or list group components based on scroll position to indicate which link is currently active in the viewport.
group: components
toc: true
---
Automatically update Bootstrap navigation or list group components based on scroll position to indicate which link is currently active in the viewport.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## How it works
Scrollspy has a few requirements to function properly:

View File

@ -1,17 +1,11 @@
---
layout: docs
title: Tooltips
description: Documentation and examples for adding custom Bootstrap tooltips with CSS and JavaScript.
description: Documentation and examples for adding custom Bootstrap tooltips with CSS and JavaScript using CSS3 for animations and data-attributes for local title storage.
group: components
toc: true
---
Inspired by the excellent Tipsy jQuery plugin written by Jason Frame. Tooltips are an updated version, which don't rely on images, use CSS3 for animations, and data-attributes for local title storage.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Overview
Things to know when using the tooltip plugin: