diff options
| author | Gijs Boddeus <[email protected]> | 2017-08-15 23:43:36 +0200 |
|---|---|---|
| committer | GitHub <[email protected]> | 2017-08-15 23:43:36 +0200 |
| commit | 06d4c6d273daf3eb84c9c5bb6306cecc9209304f (patch) | |
| tree | 695d8fb5b2f414eae0bac032369f77285f594803 /docs/components | |
| parent | 1fb6d8c46a560e2e35295440721ba2929f9721b6 (diff) | |
| parent | 7b873fa0a15c0fb62671f95e966656967c6fd9b4 (diff) | |
| download | bootstrap-06d4c6d273daf3eb84c9c5bb6306cecc9209304f.tar.xz bootstrap-06d4c6d273daf3eb84c9c5bb6306cecc9209304f.zip | |
Merge pull request #1 from twbs/v4-dev
updating fork of BS to v4-beta1
Diffstat (limited to 'docs/components')
| -rw-r--r-- | docs/components/alerts.md | 131 | ||||
| -rw-r--r-- | docs/components/badge.md | 55 | ||||
| -rw-r--r-- | docs/components/breadcrumb.md | 34 | ||||
| -rw-r--r-- | docs/components/button-group.md | 158 | ||||
| -rw-r--r-- | docs/components/buttons.md | 188 | ||||
| -rw-r--r-- | docs/components/card.md | 592 | ||||
| -rw-r--r-- | docs/components/carousel.md | 256 | ||||
| -rw-r--r-- | docs/components/collapse.md | 217 | ||||
| -rw-r--r-- | docs/components/dropdowns.md | 543 | ||||
| -rw-r--r-- | docs/components/forms.md | 976 | ||||
| -rw-r--r-- | docs/components/input-group.md | 243 | ||||
| -rw-r--r-- | docs/components/jumbotron.md | 33 | ||||
| -rw-r--r-- | docs/components/list-group.md | 150 | ||||
| -rw-r--r-- | docs/components/modal.md | 498 | ||||
| -rw-r--r-- | docs/components/navbar.md | 415 | ||||
| -rw-r--r-- | docs/components/navs.md | 491 | ||||
| -rw-r--r-- | docs/components/pagination.md | 148 | ||||
| -rw-r--r-- | docs/components/popovers.md | 346 | ||||
| -rw-r--r-- | docs/components/progress.md | 88 | ||||
| -rw-r--r-- | docs/components/scrollspy.md | 163 | ||||
| -rw-r--r-- | docs/components/tooltips.md | 322 |
21 files changed, 0 insertions, 6047 deletions
diff --git a/docs/components/alerts.md b/docs/components/alerts.md deleted file mode 100644 index b1ac0d845..000000000 --- a/docs/components/alerts.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -layout: docs -title: Alerts -description: Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages. -group: components ---- - -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). - -{% example html %} -<div class="alert alert-success" role="alert"> - <strong>Well done!</strong> You successfully read this important alert message. -</div> -<div class="alert alert-info" role="alert"> - <strong>Heads up!</strong> This alert needs your attention, but it's not super important. -</div> -<div class="alert alert-warning" role="alert"> - <strong>Warning!</strong> Better check yourself, you're not looking too good. -</div> -<div class="alert alert-danger" role="alert"> - <strong>Oh snap!</strong> Change a few things up and try submitting again. -</div> -{% endexample %} - -{% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %} -{{ callout-include | markdownify }} - -### Link color - -Use the `.alert-link` utility class to quickly provide matching colored links within any alert. - -{% example html %} -<div class="alert alert-success" role="alert"> - <strong>Well done!</strong> You successfully read <a href="#" class="alert-link">this important alert message</a>. -</div> -<div class="alert alert-info" role="alert"> - <strong>Heads up!</strong> This <a href="#" class="alert-link">alert needs your attention</a>, but it's not super important. -</div> -<div class="alert alert-warning" role="alert"> - <strong>Warning!</strong> Better check yourself, you're <a href="#" class="alert-link">not looking too good</a>. -</div> -<div class="alert alert-danger" role="alert"> - <strong>Oh snap!</strong> <a href="#" class="alert-link">Change a few things up</a> and try submitting again. -</div> -{% endexample %} - -### Additional content - -Alerts can also contain additional HTML elements like headings and paragraphs. - -{% example html %} -<div class="alert alert-success" role="alert"> - <h4 class="alert-heading">Well done!</h4> - <p>Aww yeah, you successfully read this important alert message. This example text is going to run a bit longer so that you can see how spacing within an alert works with this kind of content.</p> - <p class="mb-0">Whenever you need to, be sure to use margin utilities to keep things nice and tidy.</p> -</div> -{% endexample %} - - -### Dismissing - -Using the alert JavaScript plugin, it's possible to dismiss any alert inline. Here's how: - -- Be sure you've loaded the alert plugin, or the compiled Bootstrap JavaScript. -- Add a dismiss button and the `.alert-dismissible` class, which adds extra padding to the right of the alert and positions the `.close` button. -- On the dismiss button, add the `data-dismiss="alert"` attribute, which triggers the JavaScript functionality. Be sure to use the `<button>` element with it for proper behavior across all devices. -- To animate alerts when dismissing them, be sure to add the `.fade` and `.active` classes. - -You can see this in action with a live demo: - -{% example html %} -<div class="alert alert-warning alert-dismissible fade active" role="alert"> - <button type="button" class="close" data-dismiss="alert" aria-label="Close"> - <span aria-hidden="true">×</span> - </button> - <strong>Holy guacamole!</strong> You should check in on some of those fields below. -</div> -{% endexample %} - -## JavaScript behavior - -### Triggers - -Enable dismissal of an alert via JavaScript: - -{% highlight js %} -$(".alert").alert() -{% endhighlight %} - -Or with `data` attributes on a button **within the alert**, as demonstrated above: - -{% highlight html %} -<button type="button" class="close" data-dismiss="alert" aria-label="Close"> - <span aria-hidden="true">×</span> -</button> -{% endhighlight %} - -Note that closing an alert will remove it from the DOM. - -### Methods - -| Method | Description | -| --- | --- | -| `$().alert()` | Makes an alert listen for click events on descendant elements which have the `data-dismiss="alert"` attribute. (Not necessary when using the data-api's auto-initialization.) | -| `$().alert('close')` | Closes an alert by removing it from the DOM. If the `.fade` and `.in` classes are present on the element, the alert will fade out before it is removed. | - -{% highlight js %}$(".alert").alert('close'){% endhighlight %} - -### Events - -Bootstrap's alert plugin exposes a few events for hooking into alert functionality. - -| Event | Description | -| --- | --- | -| `close.bs.alert` | This event fires immediately when the <code>close</code> instance method is called. | -| `closed.bs.alert` | This event is fired when the alert has been closed (will wait for CSS transitions to complete). | - -{% highlight js %} -$('#myAlert').on('closed.bs.alert', function () { - // do something… -}) -{% endhighlight %} diff --git a/docs/components/badge.md b/docs/components/badge.md deleted file mode 100644 index 4e4bafcde..000000000 --- a/docs/components/badge.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -layout: docs -title: Badges -description: Documentation and examples for badges, our small count and labelling component. -group: components ---- - -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 %} -<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 %} - -## Contextual variations - -Add any of the below mentioned modifier classes to change the appearance of a badge. - -{% example html %} -<span class="badge badge-default">Default</span> -<span class="badge badge-primary">Primary</span> -<span class="badge badge-success">Success</span> -<span class="badge badge-info">Info</span> -<span class="badge badge-warning">Warning</span> -<span class="badge badge-danger">Danger</span> -{% endexample %} - -{% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %} -{{ callout-include | markdownify }} - -## Pill badges - -Use the `.badge-pill` modifier class to make badges more rounded (with a larger `border-radius` and additional horizontal `padding`). Useful if you miss the badges from v3. - -{% example html %} -<span class="badge badge-pill badge-default">Default</span> -<span class="badge badge-pill badge-primary">Primary</span> -<span class="badge badge-pill badge-success">Success</span> -<span class="badge badge-pill badge-info">Info</span> -<span class="badge badge-pill badge-warning">Warning</span> -<span class="badge badge-pill badge-danger">Danger</span> -{% endexample %} diff --git a/docs/components/breadcrumb.md b/docs/components/breadcrumb.md deleted file mode 100644 index 8beaa0ae4..000000000 --- a/docs/components/breadcrumb.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: docs -title: Breadcrumb -description: Indicate the current page's location within a navigational hierarchy. -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). - -{% example html %} -<ol class="breadcrumb"> - <li class="breadcrumb-item active">Home</li> -</ol> -<ol class="breadcrumb"> - <li class="breadcrumb-item"><a href="#">Home</a></li> - <li class="breadcrumb-item active">Library</li> -</ol> -<ol class="breadcrumb"> - <li class="breadcrumb-item"><a href="#">Home</a></li> - <li class="breadcrumb-item"><a href="#">Library</a></li> - <li class="breadcrumb-item active">Data</li> -</ol> -{% endexample %} - -Similar to our navigation components, breadcrumbs work fine with or without the usage of list markup. - -{% example html %} -<nav class="breadcrumb"> - <a class="breadcrumb-item" href="#">Home</a> - <a class="breadcrumb-item" href="#">Library</a> - <a class="breadcrumb-item" href="#">Data</a> - <span class="breadcrumb-item active">Bootstrap</span> -</nav> -{% endexample %} diff --git a/docs/components/button-group.md b/docs/components/button-group.md deleted file mode 100644 index cff38e1b1..000000000 --- a/docs/components/button-group.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -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 ---- - -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} - -## Basic example - -Wrap a series of buttons with `.btn` in `.btn-group`. - -{% example html %} -<div class="btn-group" role="group" aria-label="Basic example"> - <button type="button" class="btn btn-secondary">Left</button> - <button type="button" class="btn btn-secondary">Middle</button> - <button type="button" class="btn btn-secondary">Right</button> -</div> -{% endexample %} - -## Button toolbar - -Combine sets of button groups into button toolbars for more complex components. - -{% example html %} -<div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups"> - <div class="btn-group" role="group" aria-label="First group"> - <button type="button" class="btn btn-secondary">1</button> - <button type="button" class="btn btn-secondary">2</button> - <button type="button" class="btn btn-secondary">3</button> - <button type="button" class="btn btn-secondary">4</button> - </div> - <div class="btn-group" role="group" aria-label="Second group"> - <button type="button" class="btn btn-secondary">5</button> - <button type="button" class="btn btn-secondary">6</button> - <button type="button" class="btn btn-secondary">7</button> - </div> - <div class="btn-group" role="group" aria-label="Third group"> - <button type="button" class="btn btn-secondary">8</button> - </div> -</div> -{% endexample %} - -## Sizing - -Instead of applying button sizing classes to every button in a group, just add `.btn-group-*` to each `.btn-group`, including each one when nesting multiple groups. - -<div class="bd-example"> - <div class="btn-group btn-group-lg" role="group" aria-label="Large button group"> - <button type="button" class="btn btn-secondary">Left</button> - <button type="button" class="btn btn-secondary">Middle</button> - <button type="button" class="btn btn-secondary">Right</button> - </div> - <br> - <div class="btn-group" role="group" aria-label="Default button group"> - <button type="button" class="btn btn-secondary">Left</button> - <button type="button" class="btn btn-secondary">Middle</button> - <button type="button" class="btn btn-secondary">Right</button> - </div> - <br> - <div class="btn-group btn-group-sm" role="group" aria-label="Small button group"> - <button type="button" class="btn btn-secondary">Left</button> - <button type="button" class="btn btn-secondary">Middle</button> - <button type="button" class="btn btn-secondary">Right</button> - </div> -</div> - -{% highlight html %} -<div class="btn-group btn-group-lg" role="group" aria-label="...">...</div> -<div class="btn-group" role="group" aria-label="...">...</div> -<div class="btn-group btn-group-sm" role="group" aria-label="...">...</div> -{% endhighlight %} - -## Nesting - -Place a `.btn-group` within another `.btn-group` when you want dropdown menus mixed with a series of buttons. - -{% example html %} -<div class="btn-group" role="group" aria-label="Button group with nested dropdown"> - <button type="button" class="btn btn-secondary">1</button> - <button type="button" class="btn btn-secondary">2</button> - - <div class="btn-group" role="group"> - <button id="btnGroupDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown - </button> - <div class="dropdown-menu" aria-labelledby="btnGroupDrop1"> - <a class="dropdown-item" href="#">Dropdown link</a> - <a class="dropdown-item" href="#">Dropdown link</a> - </div> - </div> -</div> -{% endexample %} - -## Vertical variation - -Make a set of buttons appear vertically stacked rather than horizontally. **Split button dropdowns are not supported here.** - -<div class="bd-example"> - <div class="btn-group-vertical" role="group" aria-label="Vertical button group"> - <button type="button" class="btn btn-secondary">Button</button> - <button type="button" class="btn btn-secondary">Button</button> - <div class="btn-group" role="group"> - <button id="btnGroupVerticalDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown - </button> - <div class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop1"> - <a class="dropdown-item" href="#">Dropdown link</a> - <a class="dropdown-item" href="#">Dropdown link</a> - </div> - </div> - <button type="button" class="btn btn-secondary">Button</button> - <button type="button" class="btn btn-secondary">Button</button> - <div class="btn-group" role="group"> - <button id="btnGroupVerticalDrop2" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown - </button> - <div class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop2"> - <a class="dropdown-item" href="#">Dropdown link</a> - <a class="dropdown-item" href="#">Dropdown link</a> - </div> - </div> - <div class="btn-group" role="group"> - <button id="btnGroupVerticalDrop3" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown - </button> - <div class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop3"> - <a class="dropdown-item" href="#">Dropdown link</a> - <a class="dropdown-item" href="#">Dropdown link</a> - </div> - </div> - <div class="btn-group" role="group"> - <button id="btnGroupVerticalDrop4" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown - </button> - <div class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop4"> - <a class="dropdown-item" href="#">Dropdown link</a> - <a class="dropdown-item" href="#">Dropdown link</a> - </div> - </div> - </div> -</div> - -{% highlight html %} -<div class="btn-group-vertical"> - ... -</div> -{% endhighlight %} - -## Tooltips and popovers - -Due to the specific implementation (and some other components), a bit of special casing is required for tooltips and popovers within button groups. **You'll have to specify the option `container: 'body'`** to avoid unwanted side effects (such as the element growing wider and/or losing its rounded corners when the tooltip or popover is triggered). diff --git a/docs/components/buttons.md b/docs/components/buttons.md deleted file mode 100644 index 02b14f913..000000000 --- a/docs/components/buttons.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -layout: docs -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/" ---- - -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. - -{% example html %} -<!-- Provides extra visual weight and identifies the primary action in a set of buttons --> -<button type="button" class="btn btn-primary">Primary</button> - -<!-- Secondary, outline button --> -<button type="button" class="btn btn-secondary">Secondary</button> - -<!-- Indicates a successful or positive action --> -<button type="button" class="btn btn-success">Success</button> - -<!-- Contextual button for informational alert messages --> -<button type="button" class="btn btn-info">Info</button> - -<!-- Indicates caution should be taken with this action --> -<button type="button" class="btn btn-warning">Warning</button> - -<!-- Indicates a dangerous or potentially negative action --> -<button type="button" class="btn btn-danger">Danger</button> - -<!-- Deemphasize a button by making it look like a link while maintaining button behavior --> -<button type="button" class="btn btn-link">Link</button> -{% endexample %} - -{% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %} -{{ callout-include | markdownify }} - -## Button tags - -The `.btn` classes are designed to be used with the `<button>` element. However, you can also use these classes on `<a>` or `<input>` elements (though some browsers may apply a slightly different rendering). - -When using button classes on `<a>` elements that are used to trigger in-page functionality (like collapsing content), rather than linking to new pages or sections within the current page, these links should be given a `role="button"` to appropriately convey their purpose to assistive technologies such as screen readers. - -{% example html %} -<a class="btn btn-primary" href="#" role="button">Link</a> -<button class="btn btn-primary" type="submit">Button</button> -<input class="btn btn-primary" type="button" value="Input"> -<input class="btn btn-primary" type="submit" value="Submit"> -<input class="btn btn-primary" type="reset" value="Reset"> -{% endexample %} - -## Outline buttons - -In need of a button, but not the hefty background colors they bring? Replace the default modifier classes with the `.btn-outline-*` ones to remove all background images and colors on any button. - -{% example html %} -<button type="button" class="btn btn-outline-primary">Primary</button> -<button type="button" class="btn btn-outline-secondary">Secondary</button> -<button type="button" class="btn btn-outline-success">Success</button> -<button type="button" class="btn btn-outline-info">Info</button> -<button type="button" class="btn btn-outline-warning">Warning</button> -<button type="button" class="btn btn-outline-danger">Danger</button> -{% endexample %} - - -## Sizes - -Fancy larger or smaller buttons? Add `.btn-lg` or `.btn-sm` for additional sizes. - -{% example html %} -<button type="button" class="btn btn-primary btn-lg">Large button</button> -<button type="button" class="btn btn-secondary btn-lg">Large button</button> -{% endexample %} - -{% example html %} -<button type="button" class="btn btn-primary btn-sm">Small button</button> -<button type="button" class="btn btn-secondary btn-sm">Small button</button> -{% endexample %} - -Create block level buttons—those that span the full width of a parent—by adding `.btn-block`. - -{% example html %} -<button type="button" class="btn btn-primary btn-lg btn-block">Block level button</button> -<button type="button" class="btn btn-secondary btn-lg btn-block">Block level button</button> -{% endexample %} - -## Active state - -Buttons will appear pressed (with a darker background, darker border, and inset shadow) when active. **There's no need to add a class to `<button>`s as they use a pseudo-class**. However, you can still force the same active appearance with `.active` (and include the <code>aria-pressed="true"</code> attribute) should you need to replicate the state programmatically. - -{% example html %} -<a href="#" class="btn btn-primary btn-lg active" role="button" aria-pressed="true">Primary link</a> -<a href="#" class="btn btn-secondary btn-lg active" role="button" aria-pressed="true">Link</a> -{% endexample %} - -## Disabled state - -Make buttons look inactive by adding the `disabled` boolean attribute to any `<button>` element. - -{% callout info %} -**Heads up!** IE9 and below render disabled buttons with gray, shadowed text that we can't override. -{% endcallout %} - -{% example html %} -<button type="button" class="btn btn-lg btn-primary" disabled>Primary button</button> -<button type="button" class="btn btn-secondary btn-lg" disabled>Button</button> -{% endexample %} - -Disabled buttons using the `<a>` element behave a bit different: - -- `<a>`s don't support the `disabled` attribute, so you must add the `.disabled` class to make it visually appear disabled. -- Some future-friendly styles are included to disable all `pointer-events` on anchor buttons. In browsers which support that property, you won't see the disabled cursor at all. -- Disabled buttons should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies. - -{% example html %} -<a href="#" class="btn btn-primary btn-lg disabled" role="button" aria-disabled="true">Primary link</a> -<a href="#" class="btn btn-secondary btn-lg disabled" role="button" aria-disabled="true">Link</a> -{% endexample %} - -{% callout warning %} -#### Link functionality caveat - -The `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s, but that CSS property is not yet standardized. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, add a `tabindex="-1"` attribute on these links (to prevent them from receiving keyboard focus) and use custom JavaScript to disable their functionality. -{% endcallout %} - -## Button plugin - -Do more with buttons. Control button states or create groups of buttons for more components like toolbars. - -### Toggle states - -Add `data-toggle="button"` to toggle a button's `active` state. If you're pre-toggling a button, you must manually add the `.active` class **and** `aria-pressed="true"` to the `<button>`. - -{% example html %} -<button type="button" class="btn btn-primary" data-toggle="button" aria-pressed="false" autocomplete="off"> - Single toggle -</button> -{% endexample %} - -### Checkbox and radio buttons - -Bootstrap's `.button` styles can be applied to other elements, such as `<label>`s, to provide checkbox or radio style button toggling. Add `data-toggle="buttons"` to a `.btn-group` containing those modified buttons to enable toggling in their respective styles. - -The checked state for these buttons is **only updated via `click` event** on the button. If you use another method to update the input—e.g., with `<input type="reset">` or by manually applying the input's `checked` property—you'll need to toggle `.active` on the `<label>` manually. - -Note that pre-checked buttons require you to manually add the `.active` class to the input's `<label>`. - -{% example html %} -<div class="btn-group" data-toggle="buttons"> - <label class="btn btn-primary active"> - <input type="checkbox" checked autocomplete="off"> Checkbox 1 (pre-checked) - </label> - <label class="btn btn-primary"> - <input type="checkbox" autocomplete="off"> Checkbox 2 - </label> - <label class="btn btn-primary"> - <input type="checkbox" autocomplete="off"> Checkbox 3 - </label> -</div> -{% endexample %} - -{% example html %} -<div class="btn-group" data-toggle="buttons"> - <label class="btn btn-primary active"> - <input type="radio" name="options" id="option1" autocomplete="off" checked> Radio 1 (preselected) - </label> - <label class="btn btn-primary"> - <input type="radio" name="options" id="option2" autocomplete="off"> Radio 2 - </label> - <label class="btn btn-primary"> - <input type="radio" name="options" id="option3" autocomplete="off"> Radio 3 - </label> -</div> -{% endexample %} - -### Methods - -| Method | Description | -| --- | --- | -| `$().button('toggle')` |Toggles push state. Gives the button the appearance that it has been activated. | diff --git a/docs/components/card.md b/docs/components/card.md deleted file mode 100644 index 7d350708c..000000000 --- a/docs/components/card.md +++ /dev/null @@ -1,592 +0,0 @@ ---- -layout: docs -title: Cards -description: Bootstrap Cards provide a flexible and extensible content container with multiple variants and options. -group: components ---- - -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 require a small amount of markup and classes to provide you with as much control as possible. These classes and markup are flexible though and can typically be remixed and extended with ease. For example, if your card has no flush content like images, feel free to put the `.card-block` class on the `.card` element to consolidate your markup. - -{% example html %} -<div class="card"> - <img class="card-img-top" data-src="holder.js/100px180/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> -</div> -{% endexample %} - -## Content types - -Cards support a wide variety of content, including images, text, list groups, links, and more. Mix and match multiple content types to create the card you need. - -{% example html %} -<div class="card"> - <img class="card-img-top" data-src="holder.js/100px180/?text=Image cap" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> - </div> - <ul class="list-group list-group-flush"> - <li class="list-group-item">Cras justo odio</li> - <li class="list-group-item">Dapibus ac facilisis in</li> - <li class="list-group-item">Vestibulum at eros</li> - </ul> - <div class="card-block"> - <a href="#" class="card-link">Card link</a> - <a href="#" class="card-link">Another link</a> - </div> -</div> -{% endexample %} - -Lists can be added to a card by adding a list group. - -{% example html %} -<div class="card"> - <ul class="list-group list-group-flush"> - <li class="list-group-item">Cras justo odio</li> - <li class="list-group-item">Dapibus ac facilisis in</li> - <li class="list-group-item">Vestibulum at eros</li> - </ul> -</div> -{% endexample %} - -`.card-img-top` places an image to the top of the card. With `.card-text`, text can be added to the card. Text within `.card-text` can also be styled with the standard HTML tags. - -{% example html %} -<div class="card"> - <img class="card-img-top" data-src="holder.js/100px180/?text=Image cap" alt="Card image cap"> - <div class="card-block"> - <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> - </div> -</div> -{% endexample %} - -Card titles are used by adding `.card-title` to a `<h*>` tag. In the same way, links are added and placed next to each other by adding `.card-link` to a `<a>` tag. - -{% example html %} -<div class="card card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> - <a href="#" class="card-link">Card link</a> - <a href="#" class="card-link">Another link</a> -</div> -{% endexample %} - -Subtitles are used by adding a `.card-subtitle` to an `<h*>` tag. If the `.card-title` and the `.card-subtitle` items are placed in a `.card-block` item, the card title and subtitle are aligned nicely. - -The multiple content types can be easily combined to create the card you need. See below for an example. - -{% example html %} -<div class="card"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <h6 class="card-subtitle text-muted">Support card subtitle</h6> - </div> - <img data-src="holder.js/100px180/?text=Image" alt="Card image"> - <div class="card-block"> - <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> - <a href="#" class="card-link">Card link</a> - <a href="#" class="card-link">Another link</a> - </div> -</div> -{% endexample %} - -## Sizing - -Constrain the width of cards via custom CSS, our predefined grid classes, or with custom styles using our grid mixins. - -Using the grid: - -{% example html %} -<div class="row"> - <div class="col-sm-6"> - <div class="card card-block"> - <h3 class="card-title">Special title treatment</h3> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> - </div> - <div class="col-sm-6"> - <div class="card card-block"> - <h3 class="card-title">Special title treatment</h3> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> - </div> -</div> -{% endexample %} - -Using custom widths: - -{% example html %} -<div class="card card-block" style="width: 18rem;"> - <h3 class="card-title">Special title treatment</h3> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> -</div> -{% endexample %} - -## Text alignment - -You can quickly change the text alignment of any card—in its entirety or specific parts—with our [text align classes]({{ site.baseurl }}/utilities/typography/#text-alignment). - -{% example html %} -<div class="card card-block"> - <h4 class="card-title">Special title treatment</h4> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> -</div> - -<div class="card card-block text-center"> - <h4 class="card-title">Special title treatment</h4> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> -</div> - -<div class="card card-block text-right"> - <h4 class="card-title">Special title treatment</h4> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> -</div> -{% endexample %} - -## Header and footer - -Add an optional header and/or footer within a card. - -{% example html %} -<div class="card"> - <div class="card-header"> - Featured - </div> - <div class="card-block"> - <h4 class="card-title">Special title treatment</h4> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> -</div> -{% endexample %} - -Card headers can be styled by adding `.card-header` to `<h*>` elements. - -{% example html %} -<div class="card"> - <h3 class="card-header">Featured</h3> - <div class="card-block"> - <h4 class="card-title">Special title treatment</h4> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> -</div> -{% endexample %} - -{% example html %} -<div class="card"> - <div class="card-header"> - Quote - </div> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -{% endexample %} - -{% example html %} -<div class="card text-center"> - <div class="card-header"> - Featured - </div> - <div class="card-block"> - <h4 class="card-title">Special title treatment</h4> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> - <div class="card-footer text-muted"> - 2 days ago - </div> -</div> -{% endexample %} - -## Header nav - -Use Bootstrap's nav pills or tabs within a card header. Be sure to always include a `.float-*-*` utility class for proper alignment. - -{% example html %} -<div class="card text-center"> - <div class="card-header"> - <ul class="nav nav-tabs card-header-tabs float-left"> - <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 disabled" href="#">Disabled</a> - </li> - </ul> - </div> - <div class="card-block"> - <h4 class="card-title">Special title treatment</h4> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> -</div> -{% endexample %} - -{% example html %} -<div class="card text-center"> - <div class="card-header"> - <ul class="nav nav-pills card-header-pills float-left"> - <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 disabled" href="#">Disabled</a> - </li> - </ul> - </div> - <div class="card-block"> - <h4 class="card-title">Special title treatment</h4> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> -</div> -{% endexample %} - -## Image caps - -Similar to headers and footers, cards include top and bottom image caps. - -{% example html %} -<div class="card"> - <img class="card-img-top" data-src="holder.js/100px180/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> -</div> -<div class="card"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - <img class="card-img-bottom" data-src="holder.js/100px180/" alt="Card image cap"> -</div> -{% endexample %} - -## Image overlays - -Turn an image into a card background and overlay your card's text. Depending on the image, you may or may not need `.card-inverse` (see below). - -{% example html %} -<div class="card card-inverse"> - <img class="card-img" data-src="holder.js/100px270/#55595c:#373a3c/text:Card image" alt="Card image"> - <div class="card-img-overlay"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> -</div> -{% endexample %} - -## Inverted text - -By default, cards use dark text and assume a light background. You can reverse that by toggling the `color` of text within, as well as that of the card's subcomponents, with `.card-inverse`. Then, specify a dark `background-color` and `border-color` to go with it. - -You can also use `.card-inverse` with the [contextual backgrounds variants](#background-variants). - -{% example html %} -<div class="card card-inverse" style="background-color: #333; border-color: #333;"> - <div class="card-block"> - <h3 class="card-title">Special title treatment</h3> - <p class="card-text">With supporting text below as a natural lead-in to additional content.</p> - <a href="#" class="btn btn-primary">Go somewhere</a> - </div> -</div> -{% endexample %} - -## Background variants - -Cards include their own variant classes for quickly changing the `background-color` and `border-color` of a card. **Darker colors require the use of `.card-inverse`.** - -{% example html %} -<div class="card card-inverse card-primary text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-inverse card-success text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-inverse card-info text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-inverse card-warning text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-inverse card-danger text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -{% endexample %} - -{% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %} -{{ callout-include | markdownify }} - -## Outline variants - -In need of a colored card, but not the hefty background colors they bring? Replace the default modifier classes with the `.card-outline-*` ones to style just the `border-color` of a card. - -{% example html %} -<div class="card card-outline-primary text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-outline-secondary text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-outline-success text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-outline-info text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-outline-warning text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -<div class="card card-outline-danger text-center"> - <div class="card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer>Someone famous in <cite title="Source Title">Source Title</cite></footer> - </blockquote> - </div> -</div> -{% endexample %} - -## Groups - -Use card groups to render cards as a single, attached element with equal width and height columns. By default, card groups use `display: table;` and `table-layout: fixed;` to achieve their uniform sizing. However, enabling [flexbox mode]({{ site.baseurl }}/getting-started/flexbox/) can switch that to use `display: flex;` and provide the same effect. - -Only applies to small devices and above. - -{% example html %} -<div class="card-group"> - <div class="card"> - <img class="card-img-top" data-src="holder.js/100px180/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - </div> - <div class="card"> - <img class="card-img-top" data-src="holder.js/100px180/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This card has supporting text below as a natural lead-in to additional content.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - </div> - <div class="card"> - <img class="card-img-top" data-src="holder.js/100px180/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This card has even longer content than the first to show that equal height action.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - </div> -</div> -{% endexample %} - -## Decks - -Need a set of equal width and height cards that aren't attached to one another? Use card decks. By default, card decks require two wrapping elements: `.card-deck-wrapper` and a `.card-deck`. We use table styles for the sizing and the gutters on `.card-deck`. The `.card-deck-wrapper` is used to negative margin out the `border-spacing` on the `.card-deck`. - -Only applies to small devices and above. - -**ProTip!** If you enable [flexbox mode]({{ site.baseurl }}/getting-started/flexbox/), you can remove the `.card-deck-wrapper`. - -{% example html %} -<div class="card-deck-wrapper"> - <div class="card-deck"> - <div class="card"> - <img class="card-img-top" data-src="holder.js/100px200/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - </div> - <div class="card"> - <img class="card-img-top" data-src="holder.js/100px200/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This card has supporting text below as a natural lead-in to additional content.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - </div> - <div class="card"> - <img class="card-img-top" data-src="holder.js/100px200/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This card has even longer content than the first to show that equal height action.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - </div> - </div> -</div> -{% endexample %} - -## Columns - -Cards can be organized into [Masonry](http://masonry.desandro.com)-like columns with just CSS by wrapping them in `.card-columns`. Cards are ordered from top to bottom and left to right when wrapped in `.card-columns`. - -Only applies to small devices and above. - -**Heads up!** This is **not available in IE9 and below** as they have no support for the [`column-*` CSS properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Columns/Using_multi-column_layouts). - -{% example html %} -<div class="card-columns"> - <div class="card"> - <img class="card-img-top img-fluid" data-src="holder.js/100px160/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title that wraps to a new line</h4> - <p class="card-text">This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.</p> - </div> - </div> - <div class="card card-block"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer> - <small class="text-muted"> - Someone famous in <cite title="Source Title">Source Title</cite> - </small> - </footer> - </blockquote> - </div> - <div class="card"> - <img class="card-img-top img-fluid" data-src="holder.js/100px160/" alt="Card image cap"> - <div class="card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This card has supporting text below as a natural lead-in to additional content.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - </div> - <div class="card card-block card-inverse card-primary text-center"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat.</p> - <footer> - <small> - Someone famous in <cite title="Source Title">Source Title</cite> - </small> - </footer> - </blockquote> - </div> - <div class="card card-block text-center"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This card has supporting text below as a natural lead-in to additional content.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> - <div class="card"> - <img class="card-img img-fluid" data-src="holder.js/100px260/" alt="Card image"> - </div> - <div class="card card-block text-right"> - <blockquote class="card-blockquote"> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p> - <footer> - <small class="text-muted"> - Someone famous in <cite title="Source Title">Source Title</cite> - </small> - </footer> - </blockquote> - </div> - <div class="card card-block"> - <h4 class="card-title">Card title</h4> - <p class="card-text">This is a wider card with supporting text below as a natural lead-in to additional content. This card has even longer content than the first to show that equal height action.</p> - <p class="card-text"><small class="text-muted">Last updated 3 mins ago</small></p> - </div> -</div> -{% endexample %} - -Card columns can also be extended and customized with some additional code. Shown below is an extension of the `.card-columns` class using the same CSS we use—CSS columns— to generate a set of responsive tiers for changing the number of columns. - -{% highlight scss %} -.card-columns { - @include media-breakpoint-only(lg) { - column-count: 4; - } - @include media-breakpoint-only(xl) { - column-count: 5; - } -} -{% endhighlight %} diff --git a/docs/components/carousel.md b/docs/components/carousel.md deleted file mode 100644 index 3942309f0..000000000 --- a/docs/components/carousel.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -layout: docs -title: Carousel -description: A slideshow component for cycling through elements—images or slides of text—like a carousel. -group: components ---- - -A slideshow component for cycling through elements—images or slides of text—like a carousel. 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.). **Nested carousels are not supported.** - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - -## Example - -When building carousels, be sure your slides are the same size as one another. The carousel doesn't automatically crop images to the same dimensions for you across slides. - -{% example html %} -<div id="carousel-example-generic" class="carousel slide" data-ride="carousel"> - <ol class="carousel-indicators"> - <li data-target="#carousel-example-generic" data-slide-to="0" class="active"></li> - <li data-target="#carousel-example-generic" data-slide-to="1"></li> - <li data-target="#carousel-example-generic" data-slide-to="2"></li> - </ol> - <div class="carousel-inner" role="listbox"> - <div class="carousel-item active"> - <img data-src="holder.js/900x500/auto/#777:#555/text:First slide" alt="First slide"> - </div> - <div class="carousel-item"> - <img data-src="holder.js/900x500/auto/#666:#444/text:Second slide" alt="Second slide"> - </div> - <div class="carousel-item"> - <img data-src="holder.js/900x500/auto/#555:#333/text:Third slide" alt="Third slide"> - </div> - </div> - <a class="left carousel-control" href="#carousel-example-generic" role="button" data-slide="prev"> - <span class="icon-prev" aria-hidden="true"></span> - <span class="sr-only">Previous</span> - </a> - <a class="right carousel-control" href="#carousel-example-generic" role="button" data-slide="next"> - <span class="icon-next" aria-hidden="true"></span> - <span class="sr-only">Next</span> - </a> -</div> -{% endexample %} - -{% callout warning %} -#### Transition animations not supported in Internet Explorer 9 - -Bootstrap exclusively uses CSS3 for its animations, but Internet Explorer 9 doesn't support the necessary CSS properties. Thus, there are no slide transition animations when using that browser. We have intentionally decided not to include jQuery-based fallbacks for the transitions. -{% endcallout %} - -{% callout warning %} -#### Initial active element required - -The `.active` class needs to be added to one of the slides. Otherwise, the carousel will not be visible. -{% endcallout %} - -### Optional captions - -Add captions to your slides easily with the `.carousel-caption` element within any `.carousel-item`. Place just about any optional HTML within there and it will be automatically aligned and formatted. - -<div class="bd-example"> - <div id="carousel-example-captions" class="carousel slide" data-ride="carousel"> - <ol class="carousel-indicators"> - <li data-target="#carousel-example-captions" data-slide-to="0" class="active"></li> - <li data-target="#carousel-example-captions" data-slide-to="1"></li> - <li data-target="#carousel-example-captions" data-slide-to="2"></li> - </ol> - <div class="carousel-inner" role="listbox"> - <div class="carousel-item active"> - <img data-src="holder.js/900x500/auto/#777:#777" alt="First slide image"> - <div class="carousel-caption"> - <h3>First slide label</h3> - <p>Nulla vitae elit libero, a pharetra augue mollis interdum.</p> - </div> - </div> - <div class="carousel-item"> - <img data-src="holder.js/900x500/auto/#666:#666" alt="Second slide image"> - <div class="carousel-caption"> - <h3>Second slide label</h3> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> - </div> - </div> - <div class="carousel-item"> - <img data-src="holder.js/900x500/auto/#555:#555" alt="Third slide image"> - <div class="carousel-caption"> - <h3>Third slide label</h3> - <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur.</p> - </div> - </div> - </div> - <a class="left carousel-control" href="#carousel-example-captions" role="button" data-slide="prev"> - <span class="icon-prev" aria-hidden="true"></span> - <span class="sr-only">Previous</span> - </a> - <a class="right carousel-control" href="#carousel-example-captions" role="button" data-slide="next"> - <span class="icon-next" aria-hidden="true"></span> - <span class="sr-only">Next</span> - </a> - </div> -</div> - -{% highlight html %} -<div class="carousel-item"> - <img src="..." alt="..."> - <div class="carousel-caption"> - <h3>...</h3> - <p>...</p> - </div> -</div> -{% endhighlight %} - -{% callout danger %} -#### Accessibility issue - -The carousel component is generally not compliant with accessibility standards. If you need to be compliant, please consider other options for presenting your content. -{% endcallout %} - -## Usage - -### Multiple carousels - -Carousels require the use of an `id` on the outermost container (the `.carousel`) for carousel controls to function properly. When adding multiple carousels, or when changing a carousel's `id`, be sure to update the relevant controls. - -### Via data attributes - -Use data attributes to easily control the position of the carousel. `data-slide` accepts the keywords `prev` or `next`, which alters the slide position relative to its current position. Alternatively, use `data-slide-to` to pass a raw slide index to the carousel `data-slide-to="2"`, which shifts the slide position to a particular index beginning with `0`. - -The `data-ride="carousel"` attribute is used to mark a carousel as animating starting at page load. **It cannot be used in combination with (redundant and unnecessary) explicit JavaScript initialization of the same carousel.** - -### Via JavaScript - -Call carousel manually with: - -{% highlight js %} -$('.carousel').carousel() -{% endhighlight %} - -### Options - -Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-interval=""`. - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 100px;">Name</th> - <th style="width: 50px;">Type</th> - <th style="width: 50px;">Default</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>interval</td> - <td>number</td> - <td>5000</td> - <td>The amount of time to delay between automatically cycling an item. If false, carousel will not automatically cycle.</td> - </tr> - <tr> - <td>keyboard</td> - <td>boolean</td> - <td>true</td> - <td>Whether the carousel should react to keyboard events.</td> - </tr> - <tr> - <td>pause</td> - <td>string | null</td> - <td>"hover"</td> - <td>If set to <code>"hover"</code>, pauses the cycling of the carousel on <code>mouseenter</code> and resumes the cycling of the carousel on <code>mouseleave</code>. If set to <code>null</code>, hovering over the carousel won't pause it.</td> - </tr> - <tr> - <td>ride</td> - <td>string</td> - <td>false</td> - <td>Autoplays the carousel after the user manually cycles the first item. If "carousel", autoplays the carousel on load.</td> - </tr> - <tr> - <td>wrap</td> - <td>boolean</td> - <td>true</td> - <td>Whether the carousel should cycle continuously or have hard stops.</td> - </tr> - </tbody> - </table> -</div> - -### Methods - -#### `.carousel(options)` - -Initializes the carousel with an optional options `object` and starts cycling through items. - -{% highlight js %} -$('.carousel').carousel({ - interval: 2000 -}) -{% endhighlight %} - -#### `.carousel('cycle')` - -Cycles through the carousel items from left to right. - -#### `.carousel('pause')` - -Stops the carousel from cycling through items. - -#### `.carousel(number)` - -Cycles the carousel to a particular frame (0 based, similar to an array). - -#### `.carousel('prev')` - -Cycles to the previous item. - -#### `.carousel('next')` - -Cycles to the next item. - -### Events - -Bootstrap's carousel class exposes two events for hooking into carousel functionality. Both events have the following additional properties: - -- `direction`: The direction in which the carousel is sliding (either `"left"` or `"right"`). -- `relatedTarget`: The DOM element that is being slid into place as the active item. - -All carousel events are fired at the carousel itself (i.e. at the `<div class="carousel">`). - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>slide.bs.carousel</td> - <td>This event fires immediately when the <code>slide</code> instance method is invoked.</td> - </tr> - <tr> - <td>slid.bs.carousel</td> - <td>This event is fired when the carousel has completed its slide transition.</td> - </tr> - </tbody> - </table> -</div> - -{% highlight js %} -$('#myCarousel').on('slide.bs.carousel', function () { - // do something… -}) -{% endhighlight %} diff --git a/docs/components/collapse.md b/docs/components/collapse.md deleted file mode 100644 index 0ece9e453..000000000 --- a/docs/components/collapse.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -layout: docs -title: Collapse -description: Toggle the visibility of content across your project with a few classes and our JavaScript plugins. -group: components ---- - -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: - -- `.collapse` hides content -- `.collapsing` is applied during transitions -- `.collapse.active` shows content - -You can use a link with the `href` attribute, or a button with the `data-target` attribute. In both cases, the `data-toggle="collapse"` is required. - -{% example html %} -<p> - <a class="btn btn-primary" data-toggle="collapse" href="#collapseExample" aria-expanded="false" aria-controls="collapseExample"> - Link with href - </a> - <button class="btn btn-primary" type="button" data-toggle="collapse" data-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample"> - Button with data-target - </button> -</p> -<div class="collapse" id="collapseExample"> - <div class="card card-block"> - Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. - </div> -</div> -{% endexample %} - -## Accordion example - -Extend the default collapse behavior to create an accordion. - -{% example html %} -<div id="accordion" role="tablist" aria-multiselectable="true"> - <div class="card"> - <div class="card-header" role="tab" id="headingOne"> - <h5 class="mb-0"> - <a data-toggle="collapse" data-parent="#accordion" href="#collapseOne" aria-expanded="true" aria-controls="collapseOne"> - Collapsible Group Item #1 - </a> - </h5> - </div> - - <div id="collapseOne" class="collapse active" role="tabpanel" aria-labelledby="headingOne"> - <div class="card-block"> - Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. - </div> - </div> - </div> - <div class="card"> - <div class="card-header" role="tab" id="headingTwo"> - <h5 class="mb-0"> - <a class="collapsed" data-toggle="collapse" data-parent="#accordion" href="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo"> - Collapsible Group Item #2 - </a> - </h5> - </div> - <div id="collapseTwo" class="collapse" role="tabpanel" aria-labelledby="headingTwo"> - <div class="card-block"> - Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. - </div> - </div> - </div> - <div class="card"> - <div class="card-header" role="tab" id="headingThree"> - <h5 class="mb-0"> - <a class="collapsed" data-toggle="collapse" data-parent="#accordion" href="#collapseThree" aria-expanded="false" aria-controls="collapseThree"> - Collapsible Group Item #3 - </a> - </h5> - </div> - <div id="collapseThree" class="collapse" role="tabpanel" aria-labelledby="headingThree"> - <div class="card-block"> - Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. - </div> - </div> - </div> -</div> -{% endexample %} - -## Accessibility - -Be sure to add `aria-expanded` to the control element. This attribute explicitly defines the current state of the collapsible element to screen readers and similar assistive technologies. If the collapsible element is closed by default, it should have a value of `aria-expanded="false"`. If you've set the collapsible element to be open by default using the `in` class, set `aria-expanded="true"` on the control instead. The plugin will automatically toggle this attribute based on whether or not the collapsible element has been opened or closed. - -Additionally, if your control element is targeting a single collapsible element – i.e. the `data-target` attribute is pointing to an `id` selector – you may add an additional `aria-controls` attribute to the control element, containing the `id` of the collapsible element. Modern screen readers and similar assistive technologies make use of this attribute to provide users with additional shortcuts to navigate directly to the collapsible element itself. - -## Usage - -The collapse plugin utilizes a few classes to handle the heavy lifting: - -- `.collapse` hides the content -- `.collapse.active` shows the content -- `.collapsing` is added when the transition starts, and removed when it finishes - -These classes can be found in `_animation.scss`. - -### Via data attributes - -Just add `data-toggle="collapse"` and a `data-target` to the element to automatically assign control of a collapsible element. The `data-target` attribute accepts a CSS selector to apply the collapse to. Be sure to add the class `collapse` to the collapsible element. If you'd like it to default open, add the additional class `active`. - -To add accordion-like group management to a collapsible control, add the data attribute `data-parent="#selector"`. Refer to the demo to see this in action. - -### Via JavaScript - -Enable manually with: - -{% highlight js %} -$('.collapse').collapse() -{% endhighlight %} - -### Options - -Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-parent=""`. - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 100px;">Name</th> - <th style="width: 50px;">Type</th> - <th style="width: 50px;">Default</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>parent</td> - <td>selector</td> - <td>false</td> - <td>If a selector is provided, then all collapsible elements under the specified parent will be closed when this collapsible item is shown. (similar to traditional accordion behavior - this is dependent on the <code>panel</code> class)</td> - </tr> - <tr> - <td>toggle</td> - <td>boolean</td> - <td>true</td> - <td>Toggles the collapsible element on invocation</td> - </tr> - </tbody> - </table> -</div> - -### Methods - -#### `.collapse(options)` - -Activates your content as a collapsible element. Accepts an optional options `object`. - -{% highlight js %} -$('#myCollapsible').collapse({ - toggle: false -}) -{% endhighlight %} - -#### `.collapse('toggle')` - -Toggles a collapsible element to shown or hidden. - -#### `.collapse('show')` - -Shows a collapsible element. - -#### `.collapse('hide')` - -Hides a collapsible element. - -### Events - -Bootstrap's collapse class exposes a few events for hooking into collapse functionality. - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>show.bs.collapse</td> - <td>This event fires immediately when the <code>show</code> instance method is called.</td> - </tr> - <tr> - <td>shown.bs.collapse</td> - <td>This event is fired when a collapse element has been made visible to the user (will wait for CSS transitions to complete).</td> - </tr> - <tr> - <td>hide.bs.collapse</td> - <td> - This event is fired immediately when the <code>hide</code> method has been called. - </td> - </tr> - <tr> - <td>hidden.bs.collapse</td> - <td>This event is fired when a collapse element has been hidden from the user (will wait for CSS transitions to complete).</td> - </tr> - </tbody> - </table> -</div> - -{% highlight js %} -$('#myCollapsible').on('hidden.bs.collapse', function () { - // do something… -}) -{% endhighlight %} diff --git a/docs/components/dropdowns.md b/docs/components/dropdowns.md deleted file mode 100644 index 3e9948b3d..000000000 --- a/docs/components/dropdowns.md +++ /dev/null @@ -1,543 +0,0 @@ ---- -layout: docs -title: Dropdowns -description: Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin. -group: components ---- - -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} - -## Examples - -Wrap the dropdown's toggle (your button or link) and the dropdown menu within `.dropdown`, or another element that declares `position: relative;`. Dropdowns can be triggered from `<a>` or `<button>` elements to better fit your potential needs. - -### Single button dropdowns - -Any single `.btn` can be turned into a dropdown toggle with some markup changes. Here's how you can put them to work with either `<button>` elements: - -{% example html %} -<div class="dropdown active"> - <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown button - </button> - <div class="dropdown-menu" aria-labelledby="dropdownMenuButton"> - <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> -</div> -{% endexample %} - -And with `<a>` elements: - -{% example html %} -<div class="dropdown active"> - <a class="btn btn-secondary dropdown-toggle" href="https://example.com" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown link - </a> - - <div class="dropdown-menu" aria-labelledby="dropdownMenuLink"> - <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> -</div> -{% endexample %} - -The best part is you can do this with any button variant, too: - -<div class="bd-example"> - <div class="btn-group"> - <button type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Primary</button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Secondary</button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-success dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Success</button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-info dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Info</button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-warning dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Warning</button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Danger</button> - <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> - </div><!-- /btn-group --> -</div> - -{% highlight html %} -<!-- Example single danger button --> -<div class="btn-group"> - <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Action - </button> - <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> -</div> -{% endhighlight %} - -### Split button dropdowns - -Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of `.dropdown-toggle-split` for proper spacing around the dropdown caret. - -We use this extra class to reduce the horizontal `padding` on either side of the caret by 25% and remove the `margin-left` that's added for regular button dropdowns. Those extra changes keep the caret centered in the split button and provide a more appropriately sized hit area next to the main button. - -<div class="bd-example"> - <div class="btn-group"> - <button type="button" class="btn btn-primary">Primary</button> - <button type="button" class="btn btn-primary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-secondary">Secondary</button> - <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-success">Success</button> - <button type="button" class="btn btn-success dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-info">Info</button> - <button type="button" class="btn btn-info dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-warning">Warning</button> - <button type="button" class="btn btn-warning dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-danger">Danger</button> - <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div><!-- /btn-group --> -</div> - -{% highlight html %} -<!-- Example split danger button --> -<div class="btn-group"> - <button type="button" class="btn btn-danger">Action</button> - <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> -</div> -{% endhighlight %} - -## Sizing - -Button dropdowns work with buttons of all sizes, including default and split dropdown buttons. - -<div class="bd-example"> - <div class="btn-toolbar" role="toolbar"> - <div class="btn-group"> - <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Large button - </button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-lg btn-secondary">Large split button</button> - <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div><!-- /btn-group --> - </div><!-- /btn-toolbar --> - <div class="btn-toolbar" role="toolbar"> - <div class="btn-group"> - <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Small button - </button> - <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> - </div><!-- /btn-group --> - <div class="btn-group"> - <button type="button" class="btn btn-sm btn-secondary">Small split button</button> - <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div><!-- /btn-group --> - </div><!-- /btn-toolbar --> -</div><!-- /example --> - -{% highlight html %} -<!-- Large button groups (default and split) --> -<div class="btn-group"> - <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Large button - </button> - <div class="dropdown-menu"> - ... - </div> -</div> -<div class="btn-group"> - <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Large button - </button> - <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <div class="dropdown-menu"> - ... - </div> -</div> - -<!-- Small button groups (default and split) --> -<div class="btn-group"> - <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Small button - </button> - <div class="dropdown-menu"> - ... - </div> -</div> -<div class="btn-group"> - <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Small button - </button> - <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <div class="dropdown-menu"> - ... - </div> -</div> -{% endhighlight %} - -## Dropup variation - -Trigger dropdown menus above elements by adding `.dropup` to the parent element. - -<div class="bd-example"> - <div class="btn-toolbar" role="toolbar"> - <div class="btn-group dropup"> - <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropup - </button> - <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> - </div> - - <div class="btn-group dropup"> - <button type="button" class="btn btn-secondary"> - Split dropup - </button> - <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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> - </div> - </div> -</div> - -{% highlight html %} -<!-- Default dropup button --> -<div class="btn-group dropup"> - <button type="button" class="btn btn-secondary">Dropup</button> - <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <div class="dropdown-menu"> - <!-- Dropdown menu links --> - </div> -</div> - -<!-- Split dropup button --> -<div class="btn-group dropup"> - <button type="button" class="btn btn-secondary"> - Split dropup - </button> - <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <div class="dropdown-menu"> - <!-- Dropdown menu links --> - </div> -</div> -{% endhighlight %} - -## Menu items - -Historically dropdown menu contents *had* to be links, but that's no longer the case with v4. Now you can optionally use `<button>` elements in your dropdowns instead of just `<a>`s. - -{% example html %} -<div class="dropdown active"> - <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown - </button> - <div class="dropdown-menu" aria-labelledby="dropdownMenu2"> - <button class="dropdown-item" type="button">Action</button> - <button class="dropdown-item" type="button">Another action</button> - <button class="dropdown-item" type="button">Something else here</button> - </div> -</div> -{% endexample %} - -## Menu alignment - -By default, a dropdown menu is automatically positioned 100% from the top and along the left side of its parent. Add `.dropdown-menu-right` to a `.dropdown-menu` to right align the dropdown menu. - -{% callout info %} -**Heads up!** Dropdowns are positioned only with CSS and may need some additional styles for exact alignment. -{% endcallout %} - -{% example html %} -<div class="btn-group"> - <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - This dropdown's menu is right-aligned - </button> - <div class="dropdown-menu dropdown-menu-right"> - <button class="dropdown-item" type="button">Action</button> - <button class="dropdown-item" type="button">Another action</button> - <button class="dropdown-item" type="button">Something else here</button> - </div> -</div> -{% endexample %} - -## Menu headers - -Add a header to label sections of actions in any dropdown menu. - -{% example html %} -<div class="dropdown-menu"> - <h6 class="dropdown-header">Dropdown header</h6> - <a class="dropdown-item" href="#">Action</a> - <a class="dropdown-item" href="#">Another action</a> -</div> -{% endexample %} - -## Menu dividers - -Separate groups of related menu items with a divider. - -{% example html %} -<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> -{% endexample %} - -## Disabled menu items - -Add `.disabled` to items in the dropdown to **style them as disabled**. - -{% example html %} -<div class="dropdown-menu"> - <a class="dropdown-item" href="#">Regular link</a> - <a class="dropdown-item disabled" href="#">Disabled link</a> - <a class="dropdown-item" href="#">Another link</a> -</div> -{% endexample %} - -## Usage - -Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the `.active` class on the parent list item. - -On mobile devices, opening a dropdown adds a `.dropdown-backdrop` as a tap area for closing dropdown menus when tapping outside the menu, a requirement for proper iOS support. **This means that switching from an open dropdown menu to a different dropdown menu requires an extra tap on mobile.** - -Note: The `data-toggle="dropdown"` attribute is relied on for closing dropdown menus at an application level, so it's a good idea to always use it. - -### Via data attributes - -Add `data-toggle="dropdown"` to a link or button to toggle a dropdown. - -{% highlight html %} -<div class="dropdown"> - <button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown trigger - </button> - <div class="dropdown-menu" aria-labelledby="dLabel"> - ... - </div> -</div> -{% endhighlight %} - -### Via JavaScript - -Call the dropdowns via JavaScript: - -{% highlight js %} -$('.dropdown-toggle').dropdown() -{% endhighlight %} - -{% callout info %} -#### `data-toggle="dropdown"` still required - -Regardless of whether you call your dropdown via JavaScript or instead use the data-api, `data-toggle="dropdown"` is always required to be present on the dropdown's trigger element. -{% endcallout %} - -### Options - -*None.* - -### Methods - -| Method | Description | -| --- | --- | -| `$().dropdown('toggle')` | Toggles the dropdown menu of a given navbar or tabbed navigation. | - -### Events - -All dropdown events are fired at the `.dropdown-menu`'s parent element and have a `relatedTarget` property, whose value is the toggling anchor element. - -| Event | Description | -| --- | --- | -| `show.bs.dropdown` | This event fires immediately when the show instance method is called. | -| `shown.bs.dropdown` | This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete). | -| `hide.bs.dropdown` | This event is fired immediately when the hide instance method has been called. | -| `hidden.bs.dropdown`| This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete). | - -{% highlight js %} -$('#myDropdown').on('show.bs.dropdown', function () { - // do something… -}) -{% endhighlight %} diff --git a/docs/components/forms.md b/docs/components/forms.md deleted file mode 100644 index 4cbf20412..000000000 --- a/docs/components/forms.md +++ /dev/null @@ -1,976 +0,0 @@ ---- -layout: docs -title: Forms -description: Examples and usage guidelines for from controls, form layouts, and custom forms. -group: components ---- - -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. - -Remember, since Bootstrap utilizes the HTML5 doctype, **all inputs must have a `type` attribute**. - -{% example html %} -<form> - <div class="form-group"> - <label for="exampleInputEmail1">Email address</label> - <input type="email" class="form-control" id="exampleInputEmail1" aria-describedby="emailHelp" placeholder="Enter email"> - <small id="emailHelp" class="form-text text-muted">We'll never share your email with anyone else.</small> - </div> - <div class="form-group"> - <label for="exampleInputPassword1">Password</label> - <input type="password" class="form-control" id="exampleInputPassword1" placeholder="Password"> - </div> - <div class="form-group"> - <label for="exampleSelect1">Example select</label> - <select class="form-control" id="exampleSelect1"> - <option>1</option> - <option>2</option> - <option>3</option> - <option>4</option> - <option>5</option> - </select> - </div> - <div class="form-group"> - <label for="exampleSelect2">Example multiple select</label> - <select multiple class="form-control" id="exampleSelect2"> - <option>1</option> - <option>2</option> - <option>3</option> - <option>4</option> - <option>5</option> - </select> - </div> - <div class="form-group"> - <label for="exampleTextarea">Example textarea</label> - <textarea class="form-control" id="exampleTextarea" rows="3"></textarea> - </div> - <div class="form-group"> - <label for="exampleInputFile">File input</label> - <input type="file" class="form-control-file" id="exampleInputFile" aria-describedby="fileHelp"> - <small id="fileHelp" class="form-text text-muted">This is some placeholder block-level help text for the above input. It's a bit lighter and easily wraps to a new line.</small> - </div> - <fieldset class="form-group"> - <legend>Radio buttons</legend> - <div class="form-check"> - <label class="form-check-label"> - <input type="radio" class="form-check-input" name="optionsRadios" id="optionsRadios1" value="option1" checked> - Option one is this and that—be sure to include why it's great - </label> - </div> - <div class="form-check"> - <label class="form-check-label"> - <input type="radio" class="form-check-input" name="optionsRadios" id="optionsRadios2" value="option2"> - Option two can be something else and selecting it will deselect option one - </label> - </div> - <div class="form-check disabled"> - <label class="form-check-label"> - <input type="radio" class="form-check-input" name="optionsRadios" id="optionsRadios3" value="option3" disabled> - Option three is disabled - </label> - </div> - </fieldset> - <div class="form-check"> - <label class="form-check-label"> - <input type="checkbox" class="form-check-input"> - Check me out - </label> - </div> - <button type="submit" class="btn btn-primary">Submit</button> -</form> -{% endexample %} - -Below is a complete list of the specific form controls supported by Bootstrap and the classes that customize them. Additional documentation is available for each group. - -<table> - <thead> - <tr> - <th>Classes</th> - <th>Used for</th> - <th>Supported variations</th> - </tr> - </thead> - <tbody> - <tr> - <td> - {% markdown %}`.form-group`{% endmarkdown %} - </td> - <td class="text-nowrap"> - Any group of form controls - </td> - <td> - {% markdown %}Use with any block-level element like `<fieldset>` or `<div>`{% endmarkdown %} - </td> - </tr> - <tr> - <td rowspan="3"> - {% markdown %}`.form-control`{% endmarkdown %} - </td> - <td> - Textual inputs - </td> - <td> - {% markdown %}`text`, `password`, `datetime-local`, `date`, `month`, `time`, `week`, `number`, `email`, `url`, `search`, `tel`, `color`{% endmarkdown %} - </td> - </tr> - <tr> - <td> - Select menus - </td> - <td> - {% markdown %}`multiple`, `size`{% endmarkdown %} - </td> - </tr> - <tr> - <td> - Textareas - </td> - <td> - <span class="text-muted">N/A</span> - </td> - </tr> - <tr> - <td class="text-nowrap"> - {% markdown %}`.form-control-file`{% endmarkdown %} - </td> - <td> - File inputs - </td> - <td> - {% markdown %}`file`{% endmarkdown %} - </td> - </tr> - <tr> - <td class="text-nowrap"> -{% markdown %} -`.form-check` -{% endmarkdown %} - </td> - <td class="text-nowrap"> - Checkboxes and radios - </td> - <td> - <span class="text-muted">N/A</span> - </td> - </tr> - </tbody> -</table> - -### Textual inputs - -Here are examples of `.form-control` applied to each textual HTML5 `<input>` `type`. - -{% example html %} -<div class="form-group row"> - <label for="example-text-input" class="col-2 col-form-label">Text</label> - <div class="col-10"> - <input class="form-control" type="text" value="Artisanal kale" id="example-text-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-search-input" class="col-2 col-form-label">Search</label> - <div class="col-10"> - <input class="form-control" type="search" value="How do I shoot web" id="example-search-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-email-input" class="col-2 col-form-label">Email</label> - <div class="col-10"> - <input class="form-control" type="email" value="[email protected]" id="example-email-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-url-input" class="col-2 col-form-label">URL</label> - <div class="col-10"> - <input class="form-control" type="url" value="https://getbootstrap.com" id="example-url-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-tel-input" class="col-2 col-form-label">Telephone</label> - <div class="col-10"> - <input class="form-control" type="tel" value="1-(555)-555-5555" id="example-tel-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-password-input" class="col-2 col-form-label">Password</label> - <div class="col-10"> - <input class="form-control" type="password" value="hunter2" id="example-password-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-number-input" class="col-2 col-form-label">Number</label> - <div class="col-10"> - <input class="form-control" type="number" value="42" id="example-number-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-datetime-local-input" class="col-2 col-form-label">Date and time</label> - <div class="col-10"> - <input class="form-control" type="datetime-local" value="2011-08-19T13:45:00" id="example-datetime-local-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-date-input" class="col-2 col-form-label">Date</label> - <div class="col-10"> - <input class="form-control" type="date" value="2011-08-19" id="example-date-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-month-input" class="col-2 col-form-label">Month</label> - <div class="col-10"> - <input class="form-control" type="month" value="2011-08" id="example-month-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-week-input" class="col-2 col-form-label">Week</label> - <div class="col-10"> - <input class="form-control" type="week" value="2011-W33" id="example-week-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-time-input" class="col-2 col-form-label">Time</label> - <div class="col-10"> - <input class="form-control" type="time" value="13:45:00" id="example-time-input"> - </div> -</div> -<div class="form-group row"> - <label for="example-color-input" class="col-2 col-form-label">Color</label> - <div class="col-10"> - <input class="form-control" type="color" value="#563d7c" id="example-color-input"> - </div> -</div> -{% endexample %} - -## Form layouts - -Since Bootstrap applies `display: block` and `width: 100%` to almost all our form controls, forms will by default stack vertically. Additional classes can be used to vary this layout on a per-form basis. - -### Form groups - -The `.form-group` class is the easiest way to add some structure to forms. Its only purpose is to provide `margin-bottom` around a label and control pairing. As a bonus, since it's a class you can use it with `<fieldset>`s, `<div>`s, or nearly any other element. - -{% example html %} -<form> - <div class="form-group"> - <label for="formGroupExampleInput">Example label</label> - <input type="text" class="form-control" id="formGroupExampleInput" placeholder="Example input"> - </div> - <div class="form-group"> - <label for="formGroupExampleInput2">Another label</label> - <input type="text" class="form-control" id="formGroupExampleInput2" placeholder="Another input"> - </div> -</form> -{% endexample %} - -### Inline forms - -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 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. - -You may need to manually address the width and alignment of individual form controls with [spacing utilities]({{ site.baseurl }}/utilities/spacing/) (as shown below). Lastly, be sure to always include a `<label>` with each form control, even if you need to hide it from non-screenreader visitors with `.sr-only`. - -{% example html %} -<form class="form-inline"> - <label class="sr-only" for="inlineFormInput">Name</label> - <input type="text" class="form-control mb-2 mr-sm-2 mb-sm-0" id="inlineFormInput" placeholder="Jane Doe"> - - <label class="sr-only" for="inlineFormInputGroup">Username</label> - <div class="input-group mb-2 mr-sm-2 mb-sm-0"> - <div class="input-group-addon">@</div> - <input type="text" class="form-control" id="inlineFormInputGroup" placeholder="Username"> - </div> - - <div class="form-check mb-2 mr-sm-2 mb-sm-0"> - <label class="form-check-label"> - <input class="form-check-input" type="checkbox"> Remember me - </label> - </div> - - <button type="submit" class="btn btn-primary">Submit</button> -</form> -{% endexample %} - -Custom form controls and selects are also supported. - -{% example html %} -<form class="form-inline"> - <label class="mr-sm-2" for="inlineFormCustomSelect">Preference</label> - <select class="custom-select mb-2 mr-sm-2 mb-sm-0" id="inlineFormCustomSelect"> - <option selected>Choose...</option> - <option value="1">One</option> - <option value="2">Two</option> - <option value="3">Three</option> - </select> - - <label class="custom-control custom-checkbox mb-2 mr-sm-2 mb-sm-0"> - <input type="checkbox" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Remember my preference</span> - </label> - - <button type="submit" class="btn btn-primary">Submit</button> -</form> -{% endexample %} - -{% callout warning %} -#### Alternatives to hidden labels -Assistive technologies such as screen readers will have trouble with your forms if you don't include a label for every input. For these inline forms, you can hide the labels using the `.sr-only` class. There are further alternative methods of providing a label for assistive technologies, such as the `aria-label`, `aria-labelledby` or `title` attribute. If none of these are present, assistive technologies may resort to using the `placeholder` attribute, if present, but note that use of `placeholder` as a replacement for other labelling methods is not advised. -{% endcallout %} - -### Using the Grid - -For more structured form layouts that are also responsive, you can utilize Bootstrap's [predefined grid classes]({{ site.baseurl }}/layout/grid/#predefined-classes) or [mixins]({{ site.baseurl }}/layout/grid/#sass-mixins) to create horizontal forms. Add the `.row` class to form groups and use the `.col-*-*` classes to specify the width of your labels and controls. - -Be sure to add `.col-form-label` to your `<label>`s as well so they're vertically centered with their associated form controls. For `<legend>` elements, you can use `.col-form-legend` to make them appear similar to regular `<label>` elements. - -{% example html %} -<div class="container"> - <form> - <div class="form-group row"> - <label for="inputEmail3" class="col-sm-2 col-form-label">Email</label> - <div class="col-sm-10"> - <input type="email" class="form-control" id="inputEmail3" placeholder="Email"> - </div> - </div> - <div class="form-group row"> - <label for="inputPassword3" class="col-sm-2 col-form-label">Password</label> - <div class="col-sm-10"> - <input type="password" class="form-control" id="inputPassword3" placeholder="Password"> - </div> - </div> - <fieldset class="form-group row"> - <legend class="col-form-legend col-sm-2">Radios</legend> - <div class="col-sm-10"> - <div class="form-check"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios1" value="option1" checked> - Option one is this and that—be sure to include why it's great - </label> - </div> - <div class="form-check"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios2" value="option2"> - Option two can be something else and selecting it will deselect option one - </label> - </div> - <div class="form-check disabled"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios3" value="option3" disabled> - Option three is disabled - </label> - </div> - </div> - </fieldset> - <div class="form-group row"> - <label class="col-sm-2">Checkbox</label> - <div class="col-sm-10"> - <div class="form-check"> - <label class="form-check-label"> - <input class="form-check-input" type="checkbox"> Check me out - </label> - </div> - </div> - </div> - <div class="form-group row"> - <div class="offset-sm-2 col-sm-10"> - <button type="submit" class="btn btn-primary">Sign in</button> - </div> - </div> - </form> -</div> -{% endexample %} - -Grid-based form layouts also support large and small inputs. - -{% example html %} -<div class="container"> - <form> - <div class="form-group row"> - <label for="lgFormGroupInput" class="col-sm-2 col-form-label col-form-label-lg">Email</label> - <div class="col-sm-10"> - <input type="email" class="form-control form-control-lg" id="lgFormGroupInput" placeholder="[email protected]"> - </div> - </div> - <div class="form-group row"> - <label for="smFormGroupInput" class="col-sm-2 col-form-label col-form-label-sm">Email</label> - <div class="col-sm-10"> - <input type="email" class="form-control form-control-sm" id="smFormGroupInput" placeholder="[email protected]"> - </div> - </div> - </form> -</div> -{% endexample %} - - -## Checkboxes and radios - -Default checkboxes and radios are improved upon with the help of `.form-check`, **a single class for both input types that improves the layout and behavior of their HTML elements**. Checkboxes are for selecting one or several options in a list, while radios are for selecting one option from many. - -Disabled checkboxes and radios are supported, but to provide a `not-allowed` cursor on hover of the parent `<label>`, you'll need to add the `.disabled` class to the parent `.form-check`. The disabled class will also lighten the text color to help indicate the input's state. - -### Default (stacked) - -By default, any number of checkboxes and radios that are immediate sibling will be vertically stacked and appropriately spaced with `.form-check`. - -{% example html %} -<div class="form-check"> - <label class="form-check-label"> - <input class="form-check-input" type="checkbox" value=""> - Option one is this and that—be sure to include why it's great - </label> -</div> -<div class="form-check disabled"> - <label class="form-check-label"> - <input class="form-check-input" type="checkbox" value="" disabled> - Option two is disabled - </label> -</div> -{% endexample %} - -{% example html %} -<div class="form-check"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="exampleRadios" id="exampleRadios1" value="option1" checked> - Option one is this and that—be sure to include why it's great - </label> -</div> -<div class="form-check"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="exampleRadios" id="exampleRadios2" value="option2"> - Option two can be something else and selecting it will deselect option one - </label> -</div> -<div class="form-check disabled"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="exampleRadios" id="exampleRadios3" value="option3" disabled> - Option three is disabled - </label> -</div> -{% endexample %} - -### Inline - -Group checkboxes or radios on the same horizontal row by adding `.form-check-inline` to any `.form-check`. - -{% example html %} -<div class="form-check form-check-inline"> - <label class="form-check-label"> - <input class="form-check-input" type="checkbox" id="inlineCheckbox1" value="option1"> 1 - </label> -</div> -<div class="form-check form-check-inline"> - <label class="form-check-label"> - <input class="form-check-input" type="checkbox" id="inlineCheckbox2" value="option2"> 2 - </label> -</div> -<div class="form-check form-check-inline disabled"> - <label class="form-check-label"> - <input class="form-check-input" type="checkbox" id="inlineCheckbox3" value="option3" disabled> 3 - </label> -</div> -{% endexample %} - -{% example html %} -<div class="form-check form-check-inline"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="inlineRadioOptions" id="inlineRadio1" value="option1"> 1 - </label> -</div> -<div class="form-check form-check-inline"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="inlineRadioOptions" id="inlineRadio2" value="option2"> 2 - </label> -</div> -<div class="form-check form-check-inline disabled"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="inlineRadioOptions" id="inlineRadio3" value="option3" disabled> 3 - </label> -</div> -{% endexample %} - -### Without labels - -Should you have no text within the `<label>`, the input is positioned as you'd expect. **Currently only works on non-inline checkboxes and radios.** Remember to still provide some form of label for assistive technologies (for instance, using `aria-label`). - -{% example html %} -<div class="form-check"> - <label class="form-check-label"> - <input class="form-check-input" type="checkbox" id="blankCheckbox" value="option1" aria-label="..."> - </label> -</div> -<div class="form-check"> - <label class="form-check-label"> - <input class="form-check-input" type="radio" name="blankRadio" id="blankRadio1" value="option1" aria-label="..."> - </label> -</div> -{% endexample %} - -## Static controls - -When you need to place plain text next to a form label within a form, use the `.form-control-static` class on an element of your choice. Using an element like `<p>` with a default margin? Be sure to use a margin override (as shown below). - -{% example html %} -<form> - <div class="form-group row"> - <label class="col-sm-2 col-form-label">Email</label> - <div class="col-sm-10"> - <p class="form-control-static mb-0">[email protected]</p> - </div> - </div> - <div class="form-group row"> - <label for="inputPassword" class="col-sm-2 col-form-label">Password</label> - <div class="col-sm-10"> - <input type="password" class="form-control" id="inputPassword" placeholder="Password"> - </div> - </div> -</form> -{% endexample %} - -{% example html %} -<form class="form-inline"> - <div class="form-group"> - <label class="sr-only">Email</label> - <p class="form-control-static mb-0">[email protected]</p> - </div> - <div class="form-group"> - <label for="inputPassword2" class="sr-only">Password</label> - <input type="password" class="form-control" id="inputPassword2" placeholder="Password"> - </div> - <button type="submit" class="btn btn-primary">Confirm identity</button> -</form> -{% endexample %} - -## Disabled states - -Add the `disabled` boolean attribute on an input to prevent user interactions. Disabled inputs appear lighter and add a `not-allowed` cursor. - -{% highlight html %} -<input class="form-control" id="disabledInput" type="text" placeholder="Disabled input here..." disabled> -{% endhighlight %} - -Add the `disabled` attribute to a `<fieldset>` to disable all the controls within. - -{% example html %} -<form> - <fieldset disabled> - <div class="form-group"> - <label for="disabledTextInput">Disabled input</label> - <input type="text" id="disabledTextInput" class="form-control" placeholder="Disabled input"> - </div> - <div class="form-group"> - <label for="disabledSelect">Disabled select menu</label> - <select id="disabledSelect" class="form-control"> - <option>Disabled select</option> - </select> - </div> - <div class="checkbox"> - <label> - <input type="checkbox"> Can't check this - </label> - </div> - <button type="submit" class="btn btn-primary">Submit</button> - </fieldset> -</form> -{% endexample %} - -{% callout warning %} -#### Caveat about link functionality of `<a>` - -By default, browsers will treat all native form controls (`<input>`, `<select>` and `<button>` elements) inside a `<fieldset disabled>` as disabled, preventing both keyboard and mouse interactions on them. However, if your form also includes `<a ... class="btn btn-*">` elements, these will only be given a style of `pointer-events: none`. As noted in the section about [disabled state for buttons]({{ site.baseurl }}/components/buttons/#disabled-state) (and specifically in the sub-section for anchor elements), this CSS property is not yet standardized and isn't fully supported in Opera 18 and below, or in Internet Explorer 11, and won't prevent keyboard users from being able to focus or activate these links. So to be safe, use custom JavaScript to disable such links. -{% endcallout %} - -{% callout danger %} -#### Cross-browser compatibility - -While Bootstrap will apply these styles in all browsers, Internet Explorer 11 and below don't fully support the `disabled` attribute on a `<fieldset>`. Use custom JavaScript to disable the fieldset in these browsers. -{% endcallout %} - -## Readonly inputs - -Add the `readonly` boolean attribute on an input to prevent modification of the input's value. Read-only inputs appear lighter (just like disabled inputs), but retain the standard cursor. - -{% example html %} -<input class="form-control" type="text" placeholder="Readonly input here…" readonly> -{% endexample %} - -## Control sizing - -Set heights using classes like `.form-control-lg`, and set widths using grid column classes like `.col-lg-*`. - -{% example html %} -<input class="form-control form-control-lg" type="text" placeholder=".form-control-lg"> -<input class="form-control" type="text" placeholder="Default input"> -<input class="form-control form-control-sm" type="text" placeholder=".form-control-sm"> -{% endexample %} - -{% example html %} -<select class="form-control form-control-lg"> - <option>Large select</option> -</select> -<select class="form-control"> - <option>Default select</option> -</select> -<select class="form-control form-control-sm"> - <option>Small select</option> -</select> -{% endexample %} - -## Column sizing - -Wrap inputs in grid columns, or any custom parent element, to easily enforce desired widths. - -{% example html %} -<div class="row"> - <div class="col-2"> - <input type="text" class="form-control" placeholder=".col-2"> - </div> - <div class="col-3"> - <input type="text" class="form-control" placeholder=".col-3"> - </div> - <div class="col-4"> - <input type="text" class="form-control" placeholder=".col-4"> - </div> -</div> -{% endexample %} - -## Help text - -Block-level help text in forms can be created using `.form-text` (previously known as `.help-block` in v3). Inline help text can be flexibly implemented using any inline HTML element and utility classes like `.text-muted`. - -{% callout warning %} -#### Associating help text with form controls - -Help text should be explicitly associated with the form control it relates to using the `aria-describedby` attribute. This will ensure that assistive technologies – such as screen readers – will announce this help text when the user focuses or enters the control. -{% endcallout %} - -### Block level - -Block help text—for below inputs or for longer lines of help text—can be easily achieved with `.form-text`. This class includes `display: block` and adds some top margin for easy spacing from the inputs above. - -{% example html %} -<label for="inputPassword5">Password</label> -<input type="password" id="inputPassword5" class="form-control" aria-describedby="passwordHelpBlock"> -<p id="passwordHelpBlock" class="form-text text-muted"> - Your password must be 8-20 characters long, contain letters and numbers, and must not contain spaces, special characters, or emoji. -</p> -{% endexample %} - -### Inline - -Inline text can use any typical inline HTML element (be it a `<small>`, `<span>`, or something else). - -{% example html %} -<form class="form-inline"> - <div class="form-group"> - <label for="inputPassword4">Password</label> - <input type="password" id="inputPassword4" class="form-control" aria-describedby="passwordHelpInline"> - <small id="passwordHelpInline" class="text-muted"> - Must be 8-20 characters long. - </small> - </div> -</form> -{% endexample %} - -## Validation - -Bootstrap includes validation styles for danger, warning, and success states on most form controls. - -### How it works - -Here's a rundown of how they work: - -- To use, add `.has-warning`, `.has-danger`, or `.has-success` to the parent element. Any `.col-form-label`, `.form-control`, or custom form element will receive the validation styles. -- Contextual validation text, in addition to your usual form field help text, can be added with the use of `.form-control-feedback`. This text will adapt to the parent `.has-*` class. By default it only includes a bit of `margin` for spacing and a modified `color` for each state. -- Validation icons are `url()`s configured via Sass variables that are applied to `background-image` declarations for each state. -- You may use your own base64 PNGs or SVGs by updating the Sass variables and recompiling. -- Icons can also be disabled entirely by setting the variables to `none` or commenting out the source Sass. - -### Defining states - -Generally speaking, you'll want to use a particular state for specific types of feedback: - -- **Danger** is great for when there's a blocking or required field. A user *must* fill in this field properly to submit the form. -- **Warning** works well for input values that are in progress, like password strength, or soft validation before a user attempts to submit a form. -- And lastly, **success** is ideal for situations when you have per-field validation throughout a form and want to encourage a user through the rest of the fields. - -{% comment %} -{% callout warning %} -#### Conveying validation state to assistive technologies and colorblind users - -Using these validation styles to denote the state of a form control only provides a visual, color-based indication, which will not be conveyed to users of assistive technologies - such as screen readers - or to colorblind users. - -Ensure that an alternative indication of state is also provided. For instance, you can include a hint about state in the form control's `<label>` text itself (as is the case in the following code example), include a [Glyphicon]({{ site.baseurl }}/components/#glyphicons) (with appropriate alternative text using the `.sr-only` class - see the [Glyphicon examples]({{ site.baseurl }}/components/#glyphicons-examples)), or by providing an additional [help text](#forms-help-text) block. Specifically for assistive technologies, invalid form controls can also be assigned an `aria-invalid="true"` attribute. -{% endcallout %} -{% endcomment %} - -### Examples - -Here are some examples of the aforementioned classes in action. First up is your standard left-aligned fields with labels, help text, and validation messaging. - -{% example html %} -<div class="form-group has-success"> - <label class="form-control-label" for="inputSuccess1">Input with success</label> - <input type="text" class="form-control form-control-success" id="inputSuccess1"> - <div class="form-control-feedback">Success! You've done it.</div> - <small class="form-text text-muted">Example help text that remains unchanged.</small> -</div> -<div class="form-group has-warning"> - <label class="form-control-label" for="inputWarning1">Input with warning</label> - <input type="text" class="form-control form-control-warning" id="inputWarning1"> - <div class="form-control-feedback">Shucks, check the formatting of that and try again.</div> - <small class="form-text text-muted">Example help text that remains unchanged.</small> -</div> -<div class="form-group has-danger"> - <label class="form-control-label" for="inputDanger1">Input with danger</label> - <input type="text" class="form-control form-control-danger" id="inputDanger1"> - <div class="form-control-feedback">Sorry, that username's taken. Try another?</div> - <small class="form-text text-muted">Example help text that remains unchanged.</small> -</div> -{% endexample %} - -Those same states can also be used with horizontal forms. - -{% example html %} -<div class="container"> - <form> - <div class="form-group row has-success"> - <label for="inputHorizontalSuccess" class="col-sm-2 col-form-label">Email</label> - <div class="col-sm-10"> - <input type="email" class="form-control form-control-success" id="inputHorizontalSuccess" placeholder="[email protected]"> - <div class="form-control-feedback">Success! You've done it.</div> - <small class="form-text text-muted">Example help text that remains unchanged.</small> - </div> - </div> - <div class="form-group row has-warning"> - <label for="inputHorizontalWarning" class="col-sm-2 col-form-label">Email</label> - <div class="col-sm-10"> - <input type="email" class="form-control form-control-warning" id="inputHorizontalWarning" placeholder="[email protected]"> - <div class="form-control-feedback">Shucks, check the formatting of that and try again.</div> - <small class="form-text text-muted">Example help text that remains unchanged.</small> - </div> - </div> - <div class="form-group row has-danger"> - <label for="inputHorizontalDnger" class="col-sm-2 col-form-label">Email</label> - <div class="col-sm-10"> - <input type="email" class="form-control form-control-danger" id="inputHorizontalDnger" placeholder="[email protected]"> - <div class="form-control-feedback">Sorry, that username's taken. Try another?</div> - <small class="form-text text-muted">Example help text that remains unchanged.</small> - </div> - </div> - </form> -</div> -{% endexample %} - -Checkboxes and radios are also supported. - -{% example html %} -<div class="form-check has-success"> - <label class="form-check-label"> - <input type="checkbox" class="form-check-input" id="checkboxSuccess" value="option1"> - Checkbox with success - </label> -</div> -<div class="form-check has-warning"> - <label class="form-check-label"> - <input type="checkbox" class="form-check-input" id="checkboxWarning" value="option1"> - Checkbox with warning - </label> -</div> -<div class="form-check has-danger"> - <label class="form-check-label"> - <input type="checkbox" class="form-check-input" id="checkboxDanger" value="option1"> - Checkbox with danger - </label> -</div> -{% endexample %} - -## Custom forms - -For even more customization and cross browser consistency, use our completely custom form elements to replace the browser defaults. They're built on top of semantic and accessible markup, so they're solid replacements for any default form control. - -### Checkboxes and radios - -Each checkbox and radio is wrapped in a `<label>` for three reasons: - -- It provides a larger hit areas for checking the control. -- It provides a helpful and semantic wrapper to help us replace the default `<input>`s. -- It triggers the state of the `<input>` automatically, meaning no JavaScript is required. - -We hide the default `<input>` with `opacity` and use the `.custom-control-indicator` to build a new custom form indicator in its place. Unfortunately we can't build a custom one from just the `<input>` because CSS's `content` doesn't work on that element. - -We use the sibling selector (`~`) for all our `<input>` states—like `:checked`—to properly style our custom form indicator. When combined with the `.custom-control-description` class, we can also style the text for each item based on the `<input>`'s state. - -In the checked states, we use **base64 embedded SVG icons** from [Open Iconic](https://useiconic.com/open). This provides us the best control for styling and positioning across browsers and devices. - -#### Checkboxes - -{% example html %} -<label class="custom-control custom-checkbox"> - <input type="checkbox" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Check this custom checkbox</span> -</label> -{% endexample %} - -Custom checkboxes can also utilize the `:indeterminate` pseudo class when manually set via JavaScript (there is no available HTML attribute for specifying it). - -<div class="bd-example bd-example-indeterminate"> - <label class="custom-control custom-checkbox"> - <input type="checkbox" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Check this custom checkbox</span> - </label> -</div> - -If you're using jQuery, something like this should suffice: - -{% highlight js %} -$('.your-checkbox').prop('indeterminate', true) -{% endhighlight %} - -#### Radios - -{% example html %} -<label class="custom-control custom-radio"> - <input id="radio1" name="radio" type="radio" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Toggle this custom radio</span> -</label> -<label class="custom-control custom-radio"> - <input id="radio2" name="radio" type="radio" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Or toggle this other custom radio</span> -</label> -{% endexample %} - -#### Disabled - -Custom checkboxes and radios can also be disabled. Add the `disabled` boolean attribute to the `<input>` and the custom indicator and label description will be automatically styled. - -{% example html %} -<label class="custom-control custom-checkbox"> - <input type="checkbox" class="custom-control-input" disabled> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Check this custom checkbox</span> -</label> - -<label class="custom-control custom-radio"> - <input id="radio3" name="radioDisabled" type="radio" class="custom-control-input" disabled> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Toggle this custom radio</span> -</label> -{% endexample %} - -#### Validation states - -Add other states to your custom forms with our validation classes. - -{% example html %} -<div class="form-group has-success"> - <label class="custom-control custom-checkbox"> - <input type="checkbox" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Check this custom checkbox</span> - </label> -</div> -<div class="form-group has-warning"> - <label class="custom-control custom-checkbox"> - <input type="checkbox" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Check this custom checkbox</span> - </label> -</div> -<div class="form-group has-danger mb-0"> - <label class="custom-control custom-checkbox"> - <input type="checkbox" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Check this custom checkbox</span> - </label> -</div> -{% endexample %} - -#### Stacked - -Custom checkboxes and radios are inline to start. Add a parent with class `.custom-controls-stacked` to ensure each form control is on separate lines. - -{% example html %} -<div class="custom-controls-stacked"> - <label class="custom-control custom-radio"> - <input id="radioStacked1" name="radio-stacked" type="radio" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Toggle this custom radio</span> - </label> - <label class="custom-control custom-radio"> - <input id="radioStacked2" name="radio-stacked" type="radio" class="custom-control-input"> - <span class="custom-control-indicator"></span> - <span class="custom-control-description">Or toggle this other custom radio</span> - </label> -</div> -{% endexample %} - -### Select menu - -Custom `<select>` menus need only a custom class, `.custom-select` to trigger the custom styles. - -{% example html %} -<select class="custom-select"> - <option selected>Open this select menu</option> - <option value="1">One</option> - <option value="2">Two</option> - <option value="3">Three</option> -</select> -{% endexample %} - -Custom selects degrade nicely in IE9, receiving only a handful of overrides to remove the custom `background-image`. **Multiple selects (e.g., `<select multiple>`) are not currently supported.** - -### File browser - -The file input is the most gnarly of the bunch and require additional JavaScript if you'd like to hook them up with functional *Choose file...* and selected file name text. - -{% example html %} -<label class="custom-file"> - <input type="file" id="file" class="custom-file-input"> - <span class="custom-file-control"></span> -</label> -{% endexample %} - -Here's how it works: - -- We wrap the `<input>` in a `<label>` so the custom control properly triggers the file browser. -- We hide the default file `<input>` via `opacity`. -- We use `:after` to generate a custom background and directive (*Choose file...*). -- We use `:before` to generate and position the *Browse* button. -- We declare a `height` on the `<input>` for proper spacing for surrounding content. - -In other words, it's an entirely custom element, all generated via CSS. - -#### Translating or customizing the strings - -The [`:lang()` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:lang) is used to allow for easy translation of the "Browse" and "Choose file..." text into other languages. Simply override or add entries to the `$custom-file-text` SCSS variable with the relevant [language tag](https://en.wikipedia.org/wiki/IETF_language_tag) and localized strings. The English strings can be customized the same way. For example, here's how one might add a Spanish translation (Spanish's language code is `es`): - -{% highlight scss %} -$custom-file-text: ( - placeholder: ( - en: "Choose file...", - es: "Seleccionar archivo..." - ), - button-label: ( - en: "Browse", - es: "Navegar" - ) -); -{% endhighlight %} - -You'll need to set the language of your document (or subtree thereof) correctly in order for the correct text to be shown. This can be done using [the `lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) or the [`Content-Language` HTTP header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.12), among other methods. diff --git a/docs/components/input-group.md b/docs/components/input-group.md deleted file mode 100644 index 0869b70e7..000000000 --- a/docs/components/input-group.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -layout: docs -title: Input group -description: Extend form controls with the input group. -group: components ---- - -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.** - -{% example html %} -<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> -<br> -<div class="input-group"> - <input type="text" class="form-control" placeholder="Recipient's username" aria-describedby="basic-addon2"> - <span class="input-group-addon" id="basic-addon2">@example.com</span> -</div> -<br> -<label for="basic-url">Your vanity URL</label> -<div class="input-group"> - <span class="input-group-addon" id="basic-addon3">https://example.com/users/</span> - <input type="text" class="form-control" id="basic-url" aria-describedby="basic-addon3"> -</div> -<br> -<div class="input-group"> - <span class="input-group-addon">$</span> - <input type="text" class="form-control" aria-label="Amount (to the nearest dollar)"> - <span class="input-group-addon">.00</span> -</div> -<br> -<div class="input-group"> - <span class="input-group-addon">$</span> - <span class="input-group-addon">0.00</span> - <input type="text" class="form-control" aria-label="Amount (to the nearest dollar)"> -</div> -{% endexample %} - -## Sizing - -Add the relative form sizing classes to the `.input-group` itself and contents within will automatically resize—no need for repeating the form control size classes on each element. - -{% example html %} -<div class="input-group input-group-lg"> - <span class="input-group-addon" id="sizing-addon1">@</span> - <input type="text" class="form-control" placeholder="Username" aria-describedby="sizing-addon1"> -</div> -<br> -<div class="input-group"> - <span class="input-group-addon" id="sizing-addon2">@</span> - <input type="text" class="form-control" placeholder="Username" aria-describedby="sizing-addon2"> -</div> -{% endexample %} - -## Checkboxes and radio addons - -Place any checkbox or radio option within an input group's addon instead of text. - -{% example html %} -<div class="row"> - <div class="col-lg-6"> - <div class="input-group"> - <span class="input-group-addon"> - <input type="checkbox" aria-label="Checkbox for following text input"> - </span> - <input type="text" class="form-control" aria-label="Text input with checkbox"> - </div> - </div> - <div class="col-lg-6"> - <div class="input-group"> - <span class="input-group-addon"> - <input type="radio" aria-label="Radio button for following text input"> - </span> - <input type="text" class="form-control" aria-label="Text input with radio button"> - </div> - </div> -</div> -{% endexample %} - -## Multiple addons - -Multiple add-ons are supported and can be mixed with checkbox and radio input versions. - -{% example html %} -<div class="row"> - <div class="col-lg-6"> - <div class="input-group"> - <span class="input-group-addon"> - <input type="checkbox" aria-label="Checkbox for following text input"> - </span> - <span class="input-group-addon">$</span> - <input type="text" class="form-control" aria-label="Text input with checkbox"> - </div> - </div> - <div class="col-lg-6"> - <div class="input-group"> - <span class="input-group-addon">$</span> - <span class="input-group-addon">0.00</span> - <input type="text" class="form-control" aria-label="Text input with radio button"> - </div> - </div> -</div> -{% endexample %} - - -## Button addons - -Buttons in input groups must wrapped in a `.input-group-btn` for proper alignment and sizing. This is required due to default browser styles that cannot be overridden. - -{% example html %} -<div class="row"> - <div class="col-lg-6"> - <div class="input-group"> - <span class="input-group-btn"> - <button class="btn btn-secondary" type="button">Go!</button> - </span> - <input type="text" class="form-control" placeholder="Search for..."> - </div> - </div> - <div class="col-lg-6"> - <div class="input-group"> - <input type="text" class="form-control" placeholder="Search for..."> - <span class="input-group-btn"> - <button class="btn btn-secondary" type="button">Go!</button> - </span> - </div> - </div> -</div> -<br> -<div class="row"> - <div class="col-lg-offset-3 col-lg-6"> - <div class="input-group"> - <span class="input-group-btn"> - <button class="btn btn-secondary" type="button">Hate it</button> - </span> - <input type="text" class="form-control" placeholder="Product name"> - <span class="input-group-btn"> - <button class="btn btn-secondary" type="button">Love it</button> - </span> - </div> - </div> -</div> -{% endexample %} - -## Buttons with dropdowns - -{% example html %} -<div class="row"> - <div class="col-lg-6"> - <div class="input-group"> - <div class="input-group-btn"> - <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Action - </button> - <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 role="separator" class="dropdown-divider"></div> - <a class="dropdown-item" href="#">Separated link</a> - </div> - </div> - <input type="text" class="form-control" aria-label="Text input with dropdown button"> - </div> - </div> - <div class="col-lg-6"> - <div class="input-group"> - <input type="text" class="form-control" aria-label="Text input with dropdown button"> - <div class="input-group-btn"> - <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Action - </button> - <div class="dropdown-menu dropdown-menu-right"> - <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 role="separator" class="dropdown-divider"></div> - <a class="dropdown-item" href="#">Separated link</a> - </div> - </div> - </div> - </div> -</div> -{% endexample %} - -## Segmented buttons - -{% example html %} -<div class="row"> - <div class="col-lg-6"> - <div class="input-group"> - <div class="input-group-btn"> - <button type="button" class="btn btn-secondary">Action</button> - <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <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 role="separator" class="dropdown-divider"></div> - <a class="dropdown-item" href="#">Separated link</a> - </div> - </div> - <input type="text" class="form-control" aria-label="Text input with segmented button dropdown"> - </div> - </div> - <div class="col-lg-6"> - <div class="input-group"> - <input type="text" class="form-control" aria-label="Text input with segmented button dropdown"> - <div class="input-group-btn"> - <button type="button" class="btn btn-secondary">Action</button> - <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - <span class="sr-only">Toggle Dropdown</span> - </button> - <div class="dropdown-menu dropdown-menu-right"> - <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 role="separator" class="dropdown-divider"></div> - <a class="dropdown-item" href="#">Separated link</a> - </div> - </div> - </div> - </div> -</div> -{% endexample %} - -## Accessibility - -Screen readers will have trouble with your forms if you don't include a label for every input. For these input groups, ensure that any additional label or functionality is conveyed to assistive technologies. - -The exact technique to be used (`<label>` elements hidden using the `.sr-only` class, or use of the `aria-label`, `aria-labelledby`, `aria-describedby`, `title` or `placeholder` attribute) and what additional information will need to be conveyed will vary depending on the exact type of interface widget you're implementing. The examples in this section provide a few suggested, case-specific approaches. diff --git a/docs/components/jumbotron.md b/docs/components/jumbotron.md deleted file mode 100644 index 49b7ba9a3..000000000 --- a/docs/components/jumbotron.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: docs -title: Jumbotron -description: Lightweight, flexible component for showcasing hero unit style content. -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> - <p class="lead">This is a simple hero unit, a simple jumbotron-style component for calling extra attention to featured content or information.</p> - <hr class="my-4"> - <p>It uses utility classes for typography and spacing to space content out within the larger container.</p> - <p class="lead"> - <a class="btn btn-primary btn-lg" href="#" role="button">Learn more</a> - </p> -</div> -{% endexample %} - -To make the jumbotron full width, and without rounded corners, add the `.jumbotron-fluid` modifier class and add a `.container` or `.container-fluid` within. - -{% example html %} -<div class="jumbotron jumbotron-fluid"> - <div class="container"> - <h1 class="display-3">Fluid jumbotron</h1> - <p class="lead">This is a modified jumbotron that occupies the entire horizontal space of its parent.</p> - </div> -</div> -{% endexample %} diff --git a/docs/components/list-group.md b/docs/components/list-group.md deleted file mode 100644 index 820470bbb..000000000 --- a/docs/components/list-group.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -layout: docs -title: List group -description: Learn about Bootstrap's list group component for rendering series of related content. -group: components ---- - -List groups are a flexible and powerful component for displaying not only simple lists of elements, but complex ones with custom content. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - -## Basic example -The most basic list group is simply an unordered list with list items, and the proper classes. Build upon it with the options that follow, or your own CSS as needed. - -{% example html %} -<ul class="list-group"> - <li class="list-group-item">Cras justo odio</li> - <li class="list-group-item">Dapibus ac facilisis in</li> - <li class="list-group-item">Morbi leo risus</li> - <li class="list-group-item">Porta ac consectetur ac</li> - <li class="list-group-item">Vestibulum at eros</li> -</ul> -{% endexample %} - -## Badge - -Add badges to any list group item to show unread counts, activity, etc. - -{% example html %} -<ul class="list-group"> - <li class="list-group-item"> - <span class="badge badge-default badge-pill float-right">14</span> - Cras justo odio - </li> - <li class="list-group-item"> - <span class="badge badge-default badge-pill float-right">2</span> - Dapibus ac facilisis in - </li> - <li class="list-group-item"> - <span class="badge badge-default badge-pill float-right">1</span> - Morbi leo risus - </li> -</ul> -{% endexample %} - -When in flexbox mode, you'll need to rearrange the contents of your list group items. To replicate the right-aligned badges as shown above, use the following example's code. Note the [`flex-items-between` utility class]({{ site.baseurl }}/layout/flexbox-grid/#horizontal-alignment), the badge's placement, and the lack of a float utility on the badges. - -{% highlight html %} -<ul class="list-group"> - <li class="list-group-item flex-items-between"> - Cras justo odio - <span class="badge badge-default badge-pill">14</span> - </li> - <li class="list-group-item flex-items-between"> - Dapibus ac facilisis in - <span class="badge badge-default badge-pill">2</span> - </li> - <li class="list-group-item flex-items-between"> - Morbi leo risus - <span class="badge badge-default badge-pill">1</span> - </li> -</ul> -{% endhighlight %} - - -## Disabled items - -Add `.disabled` to a `.list-group-item` to gray it out to appear disabled. - -{% example html %} -<div class="list-group"> - <a href="#" class="list-group-item disabled"> - Cras justo odio - </a> - <a href="#" class="list-group-item">Dapibus ac facilisis in</a> - <a href="#" class="list-group-item">Morbi leo risus</a> - <a href="#" class="list-group-item">Porta ac consectetur ac</a> - <a href="#" class="list-group-item">Vestibulum at eros</a> -</div> -{% endexample %} - -## Anchors and buttons - -Use anchors or buttons to create actionable list group items with hover, disabled, and active states by adding `.list-group-item-action`. This separate class contains a few overrides to add compatibility for `<a>`s and `<button>`s, as well as the hover and focus states. - -Be sure to **not use the standard `.btn` classes here**. - -{% example html %} -<div class="list-group"> - <a href="#" class="list-group-item active"> - Cras justo odio - </a> - <a href="#" class="list-group-item list-group-item-action">Dapibus ac facilisis in</a> - <a href="#" class="list-group-item list-group-item-action">Morbi leo risus</a> - <a href="#" class="list-group-item list-group-item-action">Porta ac consectetur ac</a> - <a href="#" class="list-group-item list-group-item-action disabled">Vestibulum at eros</a> -</div> -{% endexample %} - -{% example html %} -<div class="list-group"> - <button type="button" class="list-group-item list-group-item-action active"> - Cras justo odio - </button> - <button type="button" class="list-group-item list-group-item-action">Dapibus ac facilisis in</button> - <button type="button" class="list-group-item list-group-item-action">Morbi leo risus</button> - <button type="button" class="list-group-item list-group-item-action">Porta ac consectetur ac</button> - <button type="button" class="list-group-item list-group-item-action disabled">Vestibulum at eros</button> -</div> -{% endexample %} - -## Contextual classes - -Use contextual classes to style list items, default or linked. Also includes `.active` state. - -{% example html %} -<div class="list-group"> - <a href="#" class="list-group-item list-group-item-action list-group-item-success">Dapibus ac facilisis in</a> - <a href="#" class="list-group-item list-group-item-action list-group-item-info">Cras sit amet nibh libero</a> - <a href="#" class="list-group-item list-group-item-action list-group-item-warning">Porta ac consectetur ac</a> - <a href="#" class="list-group-item list-group-item-action list-group-item-danger">Vestibulum at eros</a> -</div> -{% endexample %} - -{% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %} -{{ callout-include | markdownify }} - -## Custom content - -Add nearly any HTML within, even for linked list groups like the one below. - -{% example html %} -<div class="list-group"> - <a href="#" class="list-group-item list-group-item-action active"> - <h5 class="list-group-item-heading">List group item heading</h5> - <p class="list-group-item-text">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p> - </a> - <a href="#" class="list-group-item list-group-item-action"> - <h5 class="list-group-item-heading">List group item heading</h5> - <p class="list-group-item-text">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p> - </a> - <a href="#" class="list-group-item list-group-item-action"> - <h5 class="list-group-item-heading">List group item heading</h5> - <p class="list-group-item-text">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p> - </a> -</div> -{% endexample %} diff --git a/docs/components/modal.md b/docs/components/modal.md deleted file mode 100644 index 5b482f93b..000000000 --- a/docs/components/modal.md +++ /dev/null @@ -1,498 +0,0 @@ ---- -layout: docs -title: Modal -description: Learn how to use Bootstrap's modals to add dialog prompts to your site. -group: components ---- - -Modals are streamlined, but flexible, dialog prompts with the minimum required functionality and smart defaults. - -## 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: - -{% highlight js %} -$('#myModal').on('shown.bs.modal', function () { - $('#myInput').focus() -}) -{% endhighlight %} - -{% callout warning %} -#### Multiple open modals not supported - -Be sure not to open a modal while another is still visible. Showing more than one modal at a time requires custom code. -{% endcallout %} - -{% 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 %} - -{% callout warning %} -#### Mobile device caveats - -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 %} - -### Static example - -A rendered modal with header, body, and set of actions in the footer. - -<div class="bd-example bd-example-modal"> - <div class="modal"> - <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">×</span> - </button> - <h4 class="modal-title">Modal title</h4> - </div> - <div class="modal-body"> - <p>One fine body…</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> - -{% highlight html %} -<div class="modal fade"> - <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">×</span> - </button> - <h4 class="modal-title">Modal title</h4> - </div> - <div class="modal-body"> - <p>One fine body…</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 --> -{% 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. - -<div id="myModal" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" 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">×</span> - </button> - <h4 class="modal-title" id="myModalLabel">Modal title</h4> - </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> - </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 class="bd-example" style="padding-bottom: 24px;"> - <button type="button" class="btn btn-primary btn-lg" data-toggle="modal" data-target="#myModal"> - 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"> - Launch demo modal -</button> - -<!-- Modal --> -<div class="modal fade" id="myModal" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" 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">×</span> - </button> - <h4 class="modal-title" id="myModalLabel">Modal title</h4> - </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 %} - -{% 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> - -{% 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">×</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">×</span> - </button> - <h4 class="modal-title" id="mySmallModalLabel">Small modal</h4> - </div> - <div class="modal-body"> - ... - </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. - -{% highlight html %} -<div class="modal" tabindex="-1" role="dialog" aria-labelledby="..." aria-hidden="true"> - ... -</div> -{% endhighlight %} - -## Using the grid system - -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. - -{% 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">×</span></button> - <h4 class="modal-title" id="gridModalLabel">Modal title</h4> - </div> - <div class="modal-body"> - <div class="container-fluid bd-example-row"> - <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> - <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> -<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> -{% endexample %} - -## Varying modal content based on trigger button - -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`. - -{% 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">×</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> - </div> - </div> - </div> -</div> -{% endexample %} - -{% highlight js %} -$('#exampleModal').on('show.bs.modal', function (event) { - var button = $(event.relatedTarget) // Button that triggered the modal - var recipient = button.data('whatever') // Extract info from data-* attributes - // If necessary, you could initiate an AJAX request here (and then do the updating in a callback). - // Update the modal's content. We'll use jQuery here, but you could use a data binding library or other methods instead. - var modal = $(this) - modal.find('.modal-title').text('New message to ' + recipient) - modal.find('.modal-body input').val(recipient) -}) -{% endhighlight %} - -## Modals with 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. - -## 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. - -### Via data attributes - -Activate a modal without writing JavaScript. Set `data-toggle="modal"` on a controller element, like a button, along with a `data-target="#foo"` or `href="#foo"` to target a specific modal to toggle. - -{% highlight html %} -<button type="button" data-toggle="modal" data-target="#myModal">Launch modal</button> -{% endhighlight %} - -### Via JavaScript - -Call a modal with id `myModal` with a single line of JavaScript: - -{% highlight js %}$('#myModal').modal(options){% endhighlight %} - -### Options - -Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-backdrop=""`. - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 100px;">Name</th> - <th style="width: 50px;">Type</th> - <th style="width: 50px;">Default</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>backdrop</td> - <td>boolean or the string <code>'static'</code></td> - <td>true</td> - <td>Includes a modal-backdrop element. Alternatively, specify <code>static</code> for a backdrop which doesn't close the modal on click.</td> - </tr> - <tr> - <td>keyboard</td> - <td>boolean</td> - <td>true</td> - <td>Closes the modal when escape key is pressed</td> - </tr> - <tr> - <td>focus</td> - <td>boolean</td> - <td>true</td> - <td>Puts the focus on the modal when initialized.</td> - </tr> - <tr> - <td>show</td> - <td>boolean</td> - <td>true</td> - <td>Shows the modal when initialized.</td> - </tr> - </tbody> - </table> -</div> - -### Methods - -#### `.modal(options)` - -Activates your content as a modal. Accepts an optional options `object`. - -{% highlight js %} -$('#myModal').modal({ - keyboard: false -}) -{% endhighlight %} - -#### `.modal('toggle')` - -Manually toggles a modal. **Returns to the caller before the modal has actually been shown or hidden** (i.e. before the `shown.bs.modal` or `hidden.bs.modal` event occurs). - -{% highlight js %}$('#myModal').modal('toggle'){% endhighlight %} - -#### `.modal('show')` - -Manually opens a modal. **Returns to the caller before the modal has actually been shown** (i.e. before the `shown.bs.modal` event occurs). - -{% highlight js %}$('#myModal').modal('show'){% endhighlight %} - -#### `.modal('hide')` - -Manually hides a modal. **Returns to the caller before the modal has actually been hidden** (i.e. before the `hidden.bs.modal` event occurs). - -{% highlight js %}$('#myModal').modal('hide'){% endhighlight %} - -### Events - -Bootstrap's modal class exposes a few events for hooking into modal functionality. All modal events are fired at the modal itself (i.e. at the `<div class="modal">`). - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>show.bs.modal</td> - <td>This event fires immediately when the <code>show</code> instance method is called. If caused by a click, the clicked element is available as the <code>relatedTarget</code> property of the event.</td> - </tr> - <tr> - <td>shown.bs.modal</td> - <td>This event is fired when the modal has been made visible to the user (will wait for CSS transitions to complete). If caused by a click, the clicked element is available as the <code>relatedTarget</code> property of the event.</td> - </tr> - <tr> - <td>hide.bs.modal</td> - <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td> - </tr> - <tr> - <td>hidden.bs.modal</td> - <td>This event is fired when the modal has finished being hidden from the user (will wait for CSS transitions to complete).</td> - </tr> - </tbody> - </table> -</div> - -{% highlight js %} -$('#myModal').on('hidden.bs.modal', function (e) { - // do something... -}) -{% endhighlight %} diff --git a/docs/components/navbar.md b/docs/components/navbar.md deleted file mode 100644 index 06a90a212..000000000 --- a/docs/components/navbar.md +++ /dev/null @@ -1,415 +0,0 @@ ---- -layout: docs -title: Navbar -description: Documentation and examples for Bootstrap's powerful, responsive navigation header. -group: components ---- - -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 - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - -## Basics - -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 `.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 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, non-responsive light themed navbar. [See the responsive examples](#collapsible-content) for collapsing nav support. - -{% example html %} -<nav class="navbar navbar-light bg-faded"> - <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="#">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="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-right"> - <input class="form-control" type="text" placeholder="Search"> - <button class="btn btn-outline-success" type="submit">Search</button> - </form> -</nav> -{% endexample %} - -### Brand - -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"> - <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"> - <a class="nav-link disabled" href="#">Disabled</a> - </li> - </ul> -</nav> -{% endexample %} - -And because we use classes for our navs, you can avoid the list-based approach entirely if you like. - -{% example html %} -<nav class="navbar navbar-light bg-faded"> - <div class="nav navbar-nav"> - <a class="nav-item nav-link active" href="#">Home <span class="sr-only">(current)</span></a> - <a class="nav-item nav-link" href="#">Features</a> - <a class="nav-item nav-link" href="#">Pricing</a> - <a class="nav-item nav-link disabled" href="#">Disabled</a> - </div> -</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-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-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-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-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-left"> - Navbar text that's floated left - </span> -</nav> -{% endexample %} - -## Color schemes - -Theming the navbar has never been easier thanks to the combination of a simple link color modifier class and `background-color` utilities. Put another way, you specify light or dark and apply a background color. - -Here are some examples to show what we mean. - -<div class="bd-example"> - <nav class="navbar navbar-dark bg-inverse"> - <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> - </li> - <li class="nav-item"> - <a class="nav-link" href="#">Pricing</a> - </li> - <li class="nav-item"> - <a class="nav-link" href="#">About</a> - </li> - </ul> - <form class="form-inline float-right"> - <input class="form-control" type="text" placeholder="Search"> - <button class="btn btn-outline-info" type="submit">Search</button> - </form> - </nav> - <nav class="navbar navbar-dark bg-primary"> - <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> - </li> - <li class="nav-item"> - <a class="nav-link" href="#">Pricing</a> - </li> - <li class="nav-item"> - <a class="nav-link" href="#">About</a> - </li> - </ul> - <form class="form-inline float-right"> - <input class="form-control" type="text" placeholder="Search"> - <button class="btn btn-outline-secondary" type="submit">Search</button> - </form> - </nav> - <nav class="navbar navbar-light" style="background-color: #e3f2fd;"> - <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> - </li> - <li class="nav-item"> - <a class="nav-link" href="#">Pricing</a> - </li> - <li class="nav-item"> - <a class="nav-link" href="#">About</a> - </li> - </ul> - <form class="form-inline float-right"> - <input class="form-control" type="text" placeholder="Search"> - <button class="btn btn-outline-primary" type="submit">Search</button> - </form> - </nav> -</div> - -{% highlight html %} -<nav class="navbar navbar-dark bg-inverse"> - <!-- Navbar content --> -</nav> - -<nav class="navbar navbar-dark bg-primary"> - <!-- Navbar content --> -</nav> - -<nav class="navbar navbar-light" style="background-color: #e3f2fd;"> - <!-- Navbar content --> -</nav> -{% endhighlight %} - -## Containers - -Although it's not required, you can wrap a navbar in a `.container` to center it on a page or add one within to only center the contents of a [fixed or static top navbar](#placement). - -{% example html %} -<div class="container"> - <nav class="navbar navbar-light bg-faded"> - <a class="navbar-brand" href="#">Navbar</a> - </nav> -</div> -{% endexample %} - -{% example html %} -<nav class="navbar navbar-light bg-faded"> - <div class="container"> - <a class="navbar-brand" href="#">Navbar</a> - </div> -</nav> -{% endexample %} - -## Placement - -Navbars can be statically placed (their default behavior), static without rounded corners, or fixed to the top or bottom of the viewport. - -{% example html %} -<nav class="navbar navbar-full navbar-light bg-faded"> - <a class="navbar-brand" href="#">Full width</a> -</nav> -{% endexample %} - -{% example html %} -<nav class="navbar navbar-fixed-top navbar-light bg-faded"> - <a class="navbar-brand" href="#">Fixed top</a> -</nav> -{% endexample %} - -{% example html %} -<nav class="navbar navbar-fixed-bottom navbar-light bg-faded"> - <a class="navbar-brand" href="#">Fixed bottom</a> -</nav> -{% endexample %} - - -## Collapsible content - -Our collapse plugin allows you to use a `<button>` or `<a>` to toggle hidden content. - -{% example html %} -<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 text-muted p-1"> - <h4>Collapsed content</h4> - <span class="text-muted">Toggleable via the navbar brand.</span> - </div> - </div> -</nav> -{% endexample %} - -For more complex navbar patterns, like those used in Bootstrap v3, use the `.navbar-toggleable-*` classes in conjunction with the `.navbar-toggler`. These classes override our responsive utilities to show navigation only when content is meant to be shown. - -{% example html %} -<nav class="navbar navbar-light bg-faded"> - <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="#">Link</a> - </li> - <li class="nav-item"> - <a class="nav-link" href="#">Link</a> - </li> - <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/docs/components/navs.md b/docs/components/navs.md deleted file mode 100644 index 7ac1b5232..000000000 --- a/docs/components/navs.md +++ /dev/null @@ -1,491 +0,0 @@ ---- -layout: docs -title: Navs -description: Documentation and examples for how to use Bootstrap's included navigation components. -group: components ---- - -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} - -## 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 - -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**. - -{% example html %} -<ul class="nav"> - <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 %} - -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. - -{% example html %} -<nav class="nav"> - <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 %} - -### 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 %} - -The same works for a navigation built with lists. - -{% 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 %} - -### Tabs - -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"> - <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 %} - -### 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"> - <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 %} - -### Stacked pills - -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. - -{% example html %} -<ul class="nav nav-pills nav-stacked"> - <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 %} - -As always, stacked pills are possible without `<ul>`s. - -{% example html %} -<nav class="nav nav-pills nav-stacked"> - <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 %} - -## 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 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> - </li> - <li class="nav-item"> - <a class="nav-link disabled" href="#">Disabled</a> - </li> -</ul> -{% endexample %} - -### Pills with dropdowns - -{% 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> - <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 %} - -## Flexbox variations - -When in [flexbox mode]({{ site.baseurl }}/getting-started/flexbox/), tabbed and pilled navigation components gain access to additional nav styles. **These aren't available in default Bootstrap** due to a bug in table styles and responsive behavior. - -### Justified nav - -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: - -{% example html %} -<ul class="nav nav-inline 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> - </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 %} - -You can also use it on tabs: - -{% example html %} -<ul class="nav nav-tabs 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> - </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 %} - -And pills, too: - -{% example html %} -<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> - </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 %} - -### Centered nav - -Using our [flexbox utilities]({{ site.baseurl }}/layout/flexbox-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. - -{% example html %} -<ul class="nav nav-inline d-flex flex-items-center"> - <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 %} - -## 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. - -<div class="bd-example bd-example-tabs" role="tabpanel"> - <ul class="nav nav-tabs" id="myTab" role="tablist"> - <li class="nav-item"> - <a class="nav-link active" id="home-tab" data-toggle="tab" href="#home" role="tab" aria-controls="home" aria-expanded="true">Home</a> - </li> - <li class="nav-item"> - <a class="nav-link" id="profile-tab" data-toggle="tab" href="#profile" role="tab" aria-controls="profile">Profile</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" id="dropdown1-tab" href="#dropdown1" role="tab" data-toggle="tab" aria-controls="dropdown1">@fat</a> - <a class="dropdown-item" id="dropdown2-tab" href="#dropdown2" role="tab" data-toggle="tab" aria-controls="dropdown2">@mdo</a> - </div> - </li> - </ul> - <div class="tab-content" id="myTabContent"> - <div role="tabpanel" class="tab-pane fade in active" id="home" aria-labelledBy="home-tab"> - <p>Raw denim you probably haven't heard of them jean shorts Austin. Nesciunt tofu stumptown aliqua, retro synth master cleanse. Mustache cliche tempor, williamsburg carles vegan helvetica. Reprehenderit butcher retro keffiyeh dreamcatcher synth. Cosby sweater eu banh mi, qui irure terry richardson ex squid. Aliquip placeat salvia cillum iphone. Seitan aliquip quis cardigan american apparel, butcher voluptate nisi qui.</p> - </div> - <div class="tab-pane fade" id="profile" role="tabpanel" aria-labelledBy="profile-tab"> - <p>Food truck fixie locavore, accusamus mcsweeney's marfa nulla single-origin coffee squid. Exercitation +1 labore velit, blog sartorial PBR leggings next level wes anderson artisan four loko farm-to-table craft beer twee. Qui photo booth letterpress, commodo enim craft beer mlkshk aliquip jean shorts ullamco ad vinyl cillum PBR. Homo nostrud organic, assumenda labore aesthetic magna delectus mollit. Keytar helvetica VHS salvia yr, vero magna velit sapiente labore stumptown. Vegan fanny pack odio cillum wes anderson 8-bit, sustainable jean shorts beard ut DIY ethical culpa terry richardson biodiesel. Art party scenester stumptown, tumblr butcher vero sint qui sapiente accusamus tattooed echo park.</p> - </div> - <div class="tab-pane fade" id="dropdown1" role="tabpanel" aria-labelledBy="dropdown1-tab"> - <p>Etsy mixtape wayfarers, ethical wes anderson tofu before they sold out mcsweeney's organic lomo retro fanny pack lo-fi farm-to-table readymade. Messenger bag gentrify pitchfork tattooed craft beer, iphone skateboard locavore carles etsy salvia banksy hoodie helvetica. DIY synth PBR banksy irony. Leggings gentrify squid 8-bit cred pitchfork. Williamsburg banh mi whatever gluten-free, carles pitchfork biodiesel fixie etsy retro mlkshk vice blog. Scenester cred you probably haven't heard of them, vinyl craft beer blog stumptown. Pitchfork sustainable tofu synth chambray yr.</p> - </div> - <div class="tab-pane fade" id="dropdown2" role="tabpanel" aria-labelledBy="dropdown2-tab"> - <p>Trust fund seitan letterpress, keytar raw denim keffiyeh etsy art party before they sold out master cleanse gluten-free squid scenester freegan cosby sweater. Fanny pack portland seitan DIY, art party locavore wolf cliche high life echo park Austin. Cred vinyl keffiyeh DIY salvia PBR, banh mi before they sold out farm-to-table VHS viral locavore cosby sweater. Lomo wolf viral, mustache readymade thundercats keffiyeh craft beer marfa ethical. Wolf salvia freegan, sartorial keffiyeh echo park vegan.</p> - </div> - </div> -</div> - -### Using data attributes - -You can activate a tab or pill navigation without writing any JavaScript by simply specifying `data-toggle="tab"` or `data-toggle="pill"` on an element. Use these data attributes on `.nav-tabs` or `.nav-pills`. - -<div role="tabpanel"> -{% highlight html %} -<!-- Nav tabs --> -<ul class="nav nav-tabs" role="tablist"> - <li class="nav-item"> - <a class="nav-link active" data-toggle="tab" href="#home" role="tab">Home</a> - </li> - <li class="nav-item"> - <a class="nav-link" data-toggle="tab" href="#profile" role="tab">Profile</a> - </li> - <li class="nav-item"> - <a class="nav-link" data-toggle="tab" href="#messages" role="tab">Messages</a> - </li> - <li class="nav-item"> - <a class="nav-link" data-toggle="tab" href="#settings" role="tab">Settings</a> - </li> -</ul> - -<!-- Tab panes --> -<div class="tab-content"> - <div class="tab-pane active" id="home" role="tabpanel">...</div> - <div class="tab-pane" id="profile" role="tabpanel">...</div> - <div class="tab-pane" id="messages" role="tabpanel">...</div> - <div class="tab-pane" id="settings" role="tabpanel">...</div> -</div> -{% endhighlight %} -</div> - -### Via JavaScript - -Enable tabbable tabs via JavaScript (each tab needs to be activated individually): - -{% highlight js %} -$('#myTab a').click(function (e) { - e.preventDefault() - $(this).tab('show') -}) -{% endhighlight %} - -You can activate individual tabs in several ways: - -{% highlight js %} -$('#myTab a[href="#profile"]').tab('show') // Select tab by name -$('#myTab a:first').tab('show') // Select first tab -$('#myTab a:last').tab('show') // Select last tab -$('#myTab li:eq(2) a').tab('show') // Select third tab (0-indexed) -{% endhighlight %} - -### Fade effect - -To make tabs fade in, add `.fade` to each `.tab-pane`. The first tab pane must also have `.in` to make the initial content visible. - -{% highlight html %} -<div class="tab-content"> - <div class="tab-pane fade in active" id="home" role="tabpanel">...</div> - <div class="tab-pane fade" id="profile" role="tabpanel">...</div> - <div class="tab-pane fade" id="messages" role="tabpanel">...</div> - <div class="tab-pane fade" id="settings" role="tabpanel">...</div> -</div> -{% endhighlight %} - -### Methods - -#### $().tab - -Activates a tab element and content container. Tab should have either a `data-target` or an `href` targeting a container node in the DOM. - -{% highlight html %} -<ul class="nav nav-tabs" id="myTab" role="tablist"> - <li class="nav-item"> - <a class="nav-link active" data-toggle="tab" href="#home" role="tab" aria-controls="home">Home</a> - </li> - <li class="nav-item"> - <a class="nav-link" data-toggle="tab" href="#profile" role="tab" aria-controls="profile">Profile</a> - </li> - <li class="nav-item"> - <a class="nav-link" data-toggle="tab" href="#messages" role="tab" aria-controls="messages">Messages</a> - </li> - <li class="nav-item"> - <a class="nav-link" data-toggle="tab" href="#settings" role="tab" aria-controls="settings">Settings</a> - </li> -</ul> - -<div class="tab-content"> - <div class="tab-pane active" id="home" role="tabpanel">...</div> - <div class="tab-pane" id="profile" role="tabpanel">...</div> - <div class="tab-pane" id="messages" role="tabpanel">...</div> - <div class="tab-pane" id="settings" role="tabpanel">...</div> -</div> - -<script> - $(function () { - $('#myTab a:last').tab('show') - }) -</script> -{% endhighlight %} - -#### .tab('show') - -Selects the given tab and shows its associated pane. Any other tab that was previously selected becomes unselected and its associated pane is hidden. **Returns to the caller before the tab pane has actually been shown** (i.e. before the `shown.bs.tab` event occurs). - -{% highlight js %} -$('#someTab').tab('show') -{% endhighlight %} - -### Events - -When showing a new tab, the events fire in the following order: - -1. `hide.bs.tab` (on the current active tab) -2. `show.bs.tab` (on the to-be-shown tab) -3. `hidden.bs.tab` (on the previous active tab, the same one as for the `hide.bs.tab` event) -4. `shown.bs.tab` (on the newly-active just-shown tab, the same one as for the `show.bs.tab` event) - -If no tab was already active, then the `hide.bs.tab` and `hidden.bs.tab` events will not be fired. - -<table class="table table-bordered table-striped table-responsive"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>show.bs.tab</td> - <td>This event fires on tab show, but before the new tab has been shown. Use <code>event.target</code> and <code>event.relatedTarget</code> to target the active tab and the previous active tab (if available) respectively.</td> - </tr> - <tr> - <td>shown.bs.tab</td> - <td>This event fires on tab show after a tab has been shown. Use <code>event.target</code> and <code>event.relatedTarget</code> to target the active tab and the previous active tab (if available) respectively.</td> - </tr> - <tr> - <td>hide.bs.tab</td> - <td>This event fires when a new tab is to be shown (and thus the previous active tab is to be hidden). Use <code>event.target</code> and <code>event.relatedTarget</code> to target the current active tab and the new soon-to-be-active tab, respectively.</td> - </tr> - <tr> - <td>hidden.bs.tab</td> - <td>This event fires after a new tab is shown (and thus the previous active tab is hidden). Use <code>event.target</code> and <code>event.relatedTarget</code> to target the previous active tab and the new active tab, respectively.</td> - </tr> - </tbody> -</table> - -{% highlight js %} -$('a[data-toggle="tab"]').on('shown.bs.tab', function (e) { - e.target // newly activated tab - e.relatedTarget // previous active tab -}) -{% endhighlight %} diff --git a/docs/components/pagination.md b/docs/components/pagination.md deleted file mode 100644 index 7a454a51f..000000000 --- a/docs/components/pagination.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -layout: docs -title: Pagination -description: Documentation and examples for showing pagination links. -group: components ---- - -Provide pagination links for your site or app with the multi-page pagination component. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - -## Overview - -Simple pagination inspired by Rdio, great for apps and search results. The large block is hard to miss, easily scalable, and provides large click areas. - -{% example html %} -<nav aria-label="Page navigation"> - <ul class="pagination"> - <li class="page-item"> - <a class="page-link" href="#" aria-label="Previous"> - <span aria-hidden="true">«</span> - <span class="sr-only">Previous</span> - </a> - </li> - <li class="page-item"><a class="page-link" href="#">1</a></li> - <li class="page-item"><a class="page-link" href="#">2</a></li> - <li class="page-item"><a class="page-link" href="#">3</a></li> - <li class="page-item"><a class="page-link" href="#">4</a></li> - <li class="page-item"><a class="page-link" href="#">5</a></li> - <li class="page-item"> - <a class="page-link" href="#" aria-label="Next"> - <span aria-hidden="true">»</span> - <span class="sr-only">Next</span> - </a> - </li> - </ul> -</nav> -{% endexample %} - -{% callout info %} -### Labelling the pagination component - -The pagination component should be wrapped in a `<nav>` element to identify it as a navigation section to screen readers and other assistive technologies. In addition, as a page is likely to have more than one such navigation section already (such as the primary navigation in the header, or a sidebar navigation), it is advisable to provide a descriptive `aria-label` for the `<nav>` which reflects its purpose. For example, if the pagination component is used to navigate between a set of search results, an appropriate label could be `aria-label="Search results pages"`. -{% endcallout %} - -## Disabled and active states - -Links are customizable for different circumstances. Use `.disabled` for unclickable links and `.active` to indicate the current page. - -{% callout warning %} -#### Link functionality caveat - -The `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s, but that CSS property is not yet standardized. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, add a `tabindex="-1"` attribute on these links (to prevent them from receiving keyboard focus) and use custom JavaScript to disable their functionality. -{% endcallout %} - -{% example html %} -<nav aria-label="..."> - <ul class="pagination"> - <li class="page-item disabled"> - <a class="page-link" href="#" tabindex="-1" aria-label="Previous"> - <span aria-hidden="true">«</span> - <span class="sr-only">Previous</span> - </a> - </li> - <li class="page-item active"> - <a class="page-link" href="#">1 <span class="sr-only">(current)</span></a> - </li> - <li class="page-item"><a class="page-link" href="#">2</a></li> - <li class="page-item"><a class="page-link" href="#">3</a></li> - <li class="page-item"><a class="page-link" href="#">4</a></li> - <li class="page-item"><a class="page-link" href="#">5</a></li> - <li class="page-item"> - <a class="page-link" href="#" aria-label="Next"> - <span aria-hidden="true">»</span> - <span class="sr-only">Next</span> - </a> - </li> - </ul> -</nav> -{% endexample %} - -You can optionally swap out active or disabled anchors for `<span>`, or omit the anchor in the case of the prev/next arrows, to remove click functionality and prevent keyboard focus while retaining intended styles. - -{% example html %} -<nav aria-label="..."> - <ul class="pagination"> - <li class="page-item disabled"> - <span class="page-link" aria-label="Previous"> - <span aria-hidden="true">«</span> - <span class="sr-only">Previous</span> - </span> - </li> - <li class="page-item active"><span class="page-link">1 <span class="sr-only">(current)</span></span></li> - </ul> -</nav> -{% endexample %} - - -## Sizing - -Fancy larger or smaller pagination? Add `.pagination-lg` or `.pagination-sm` for additional sizes. - -{% example html %} -<nav aria-label="..."> - <ul class="pagination pagination-lg"> - <li class="page-item"> - <a class="page-link" href="#" aria-label="Previous"> - <span aria-hidden="true">«</span> - <span class="sr-only">Previous</span> - </a> - </li> - <li class="page-item"><a class="page-link" href="#">1</a></li> - <li class="page-item"><a class="page-link" href="#">2</a></li> - <li class="page-item"><a class="page-link" href="#">3</a></li> - <li class="page-item"> - <a class="page-link" href="#" aria-label="Next"> - <span aria-hidden="true">»</span> - <span class="sr-only">Next</span> - </a> - </li> - </ul> -</nav> -{% endexample %} - -{% example html %} -<nav aria-label="..."> - <ul class="pagination pagination-sm"> - <li class="page-item"> - <a class="page-link" href="#" aria-label="Previous"> - <span aria-hidden="true">«</span> - <span class="sr-only">Previous</span> - </a> - </li> - <li class="page-item"><a class="page-link" href="#">1</a></li> - <li class="page-item"><a class="page-link" href="#">2</a></li> - <li class="page-item"><a class="page-link" href="#">3</a></li> - <li class="page-item"> - <a class="page-link" href="#" aria-label="Next"> - <span aria-hidden="true">»</span> - <span class="sr-only">Next</span> - </a> - </li> - </ul> -</nav> -{% endexample %} diff --git a/docs/components/popovers.md b/docs/components/popovers.md deleted file mode 100644 index 1357cefcb..000000000 --- a/docs/components/popovers.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -layout: docs -title: Popovers -description: Documentation and examples for adding Bootstrap popovers to your site. -group: components ---- - -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: - - -- Popovers rely on the 3rd party library [Tether](http://tether.io/) for positioning. You must include [tether.min.js](https://github.com/HubSpot/tether/blob/master/dist/js/tether.min.js) before bootstrap.js in order for popovers to work! -- Popovers require the [tooltip plugin]({{ site.baseurl }}/components/tooltips/) as a dependency. -- Popovers are opt-in for performance reasons, so **you must initialize them yourself**. -- Zero-length `title` and `content` values will never show a popover. -- Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc). -- Triggering popovers on hidden elements will not work. -- Popovers for `.disabled` or `disabled` elements must be triggered on a wrapper element. -- When triggered from hyperlinks that span multiple lines, popovers will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior. - -Got all that? Great, let's see how they work with some examples. - -## Example: Enable popovers everywhere - -One way to initialize all popovers on a page would be to select them by their `data-toggle` attribute: - -{% highlight js %} -$(function () { - $('[data-toggle="popover"]').popover() -}) -{% endhighlight %} - -## Example: Using the `container` option - -When you have some styles on a parent element that interfere with a popover, you'll want to specify a custom `container` so that the popover's HTML appears within that element instead. - -{% highlight js %} -$(function () { - $('.example-popover').popover({ - container: 'body' - }) -}) -{% endhighlight %} - -## Static popover - -Four options are available: top, right, bottom, and left aligned. - -<div class="bd-example bd-example-popover-static"> - <div class="popover popover-top"> - <h3 class="popover-title">Popover top</h3> - <div class="popover-content"> - <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p> - </div> - </div> - - <div class="popover popover-right"> - <h3 class="popover-title">Popover right</h3> - <div class="popover-content"> - <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p> - </div> - </div> - - <div class="popover popover-bottom"> - <h3 class="popover-title">Popover bottom</h3> - - <div class="popover-content"> - <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p> - </div> - </div> - - <div class="popover popover-left"> - <h3 class="popover-title">Popover left</h3> - <div class="popover-content"> - <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p> - </div> - </div> - - <div class="clearfix"></div> -</div> - -## Live demo - -{% example html %} -<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button> -{% endexample %} - -### Four directions - -<div class="bd-example popover-demo"> - <div class="bd-example-popovers"> - <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on top - </button> - <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on right - </button> - <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on bottom - </button> - <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on left - </button> - </div> -</div> - -{% highlight html %} -<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on top -</button> - -<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on right -</button> - -<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus -sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on bottom -</button> - -<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."> - Popover on left -</button> -{% endhighlight %} - -### Dismiss on next click - -Use the `focus` trigger to dismiss popovers on the next click that the user makes. - -{% callout danger %} -#### Specific markup required for dismiss-on-next-click - -For proper cross-browser and cross-platform behavior, you must use the `<a>` tag, _not_ the `<button>` tag, and you also must include a [`tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute. -{% endcallout %} - -{% example html %} -<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a> -{% endexample %} - -{% highlight js %} -$('.popover-dismiss').popover({ - trigger: 'focus' -}) -{% endhighlight %} - - - -## Usage - -Enable popovers via JavaScript: - -{% highlight js %}$('#example').popover(options){% endhighlight %} - -### Options - -Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`. - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 100px;">Name</th> - <th style="width: 100px;">Type</th> - <th style="width: 50px;">Default</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>animation</td> - <td>boolean</td> - <td>true</td> - <td>Apply a CSS fade transition to the popover</td> - </tr> - <tr> - <td>container</td> - <td>string | false</td> - <td>false</td> - <td> - <p>Appends the popover to a specific element. Example: <code>container: 'body'</code>. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.</p> - </td> - </tr> - <tr> - <td>content</td> - <td>string | element | function</td> - <td>''</td> - <td> - <p>Default content value if <code>data-content</code> attribute isn't present.</p> - <p>If a function is given, it will be called with its <code>this</code> reference set to the element that the popover is attached to.</p> - </td> - </tr> - <tr> - <td>delay</td> - <td>number | object</td> - <td>0</td> - <td> - <p>Delay showing and hiding the popover (ms) - does not apply to manual trigger type</p> - <p>If a number is supplied, delay is applied to both hide/show</p> - <p>Object structure is: <code>delay: { "show": 500, "hide": 100 }</code></p> - </td> - </tr> - <tr> - <td>html</td> - <td>boolean</td> - <td>false</td> - <td>Insert HTML into the popover. If false, jQuery's <code>text</code> method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.</td> - </tr> - <tr> - <td>placement</td> - <td>string | function</td> - <td>'right'</td> - <td> - <p>How to position the popover - top | bottom | left | right | auto.<br>When "auto" is specified, it will dynamically reorient the popover. For example, if placement is "auto left", the popover will display to the left when possible, otherwise it will display right.</p> - <p>When a function is used to determine the placement, it is called with the popover DOM node as its first argument and the triggering element DOM node as its second. The <code>this</code> context is set to the popover instance.</p> - </td> - </tr> - <tr> - <td>selector</td> - <td>string</td> - <td>false</td> - <td>If a selector is provided, popover objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added. See <a href="https://github.com/twbs/bootstrap/issues/4215">this</a> and <a href="https://jsbin.com/zopod/1/edit">an informative example</a>.</td> - </tr> - <tr> - <td>template</td> - <td>string</td> - <td><code>'<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-title"></h3><div class="popover-content"></div></div>'</code></td> - <td> - <p>Base HTML to use when creating the popover.</p> - <p>The popover's <code>title</code> will be injected into the <code>.popover-title</code>.</p> - <p>The popover's <code>content</code> will be injected into the <code>.popover-content</code>.</p> - <p><code>.popover-arrow</code> will become the popover's arrow.</p> - <p>The outermost wrapper element should have the <code>.popover</code> class.</p> - </td> - </tr> - <tr> - <td>title</td> - <td>string | element | function</td> - <td>''</td> - <td> - <p>Default title value if <code>title</code> attribute isn't present.</p> - <p>If a function is given, it will be called with its <code>this</code> reference set to the element that the popover is attached to.</p> - </td> - </tr> - <tr> - <td>trigger</td> - <td>string</td> - <td>'click'</td> - <td>How popover is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. `manual` cannot be combined with any other trigger.</td> - </tr> - <tr> - <td>constraints</td> - <td>Array</td> - <td>'hover focus'</td> - <td>An array of constraints - passed through to Tether. For more information refer to Tether's <a href="http://tether.io/#constraints">constraint docs</a>.</td> - </tr> - <tr> - <td>offset</td> - <td>string</td> - <td>'0 0'</td> - <td>Offset of the popover relative to its target. For more information refer to Tether's <a href="http://tether.io/#offset">offset docs</a>.</td> - </tr> - </tbody> - </table> -</div> - -{% callout info %} -#### Data attributes for individual popovers - -Options for individual popovers can alternatively be specified through the use of data attributes, as explained above. -{% endcallout %} - -### Methods - -#### `$().popover(options)` - -Initializes popovers for an element collection. - -#### `.popover('show')` - -Reveals an element's popover. **Returns to the caller before the popover has actually been shown** (i.e. before the `shown.bs.popover` event occurs). This is considered a "manual" triggering of the popover. Popovers whose both title and content are zero-length are never displayed. - -{% highlight js %}$('#element').popover('show'){% endhighlight %} - -#### `.popover('hide')` - -Hides an element's popover. **Returns to the caller before the popover has actually been hidden** (i.e. before the `hidden.bs.popover` event occurs). This is considered a "manual" triggering of the popover. - -{% highlight js %}$('#element').popover('hide'){% endhighlight %} - -#### `.popover('toggle')` - -Toggles an element's popover. **Returns to the caller before the popover has actually been shown or hidden** (i.e. before the `shown.bs.popover` or `hidden.bs.popover` event occurs). This is considered a "manual" triggering of the popover. - -{% highlight js %}$('#element').popover('toggle'){% endhighlight %} - -#### `.popover('dispose')` - -Hides and destroys an element's popover. Popovers that use delegation (which are created using [the `selector` option](#options)) cannot be individually destroyed on descendant trigger elements. - - -{% highlight js %}$('#element').popover('dispose'){% endhighlight %} - -### Events - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>show.bs.popover</td> - <td>This event fires immediately when the <code>show</code> instance method is called.</td> - </tr> - <tr> - <td>shown.bs.popover</td> - <td>This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).</td> - </tr> - <tr> - <td>hide.bs.popover</td> - <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td> - </tr> - <tr> - <td>hidden.bs.popover</td> - <td>This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).</td> - </tr> - </tbody> - </table> -</div> - -{% highlight js %} -$('#myPopover').on('hidden.bs.popover', function () { - // do something… -}) -{% endhighlight %} diff --git a/docs/components/progress.md b/docs/components/progress.md deleted file mode 100644 index 50d1f1b55..000000000 --- a/docs/components/progress.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -layout: docs -title: Progress -description: Documentation and examples for using Bootstrap progress bars. -group: components ---- - -Stylize [the HTML5 `<progress>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress) with a few extra classes and some crafty browser-specific CSS. Be sure to read up on the browser support. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - -## Example - -To caption a progress bar, simply add a `<div>` with your caption text, [align the text using a utility class]({{ site.baseurl }}/utilities/typography/#text-alignment), and associate the caption with the `<progress>` element using the `aria-describedby` attribute. - -{% example html %} - -<div class="text-center" id="example-caption-1">Reticulating splines… 0%</div> -<progress class="progress" value="0" max="100" aria-describedby="example-caption-1"></progress> - -<div class="text-center" id="example-caption-2">Reticulating splines… 25%</div> -<progress class="progress" value="25" max="100" aria-describedby="example-caption-2"></progress> - -<div class="text-center" id="example-caption-3">Reticulating splines… 50%</div> -<progress class="progress" value="50" max="100" aria-describedby="example-caption-3"></progress> - -<div class="text-center" id="example-caption-4">Reticulating splines… 75%</div> -<progress class="progress" value="75" max="100" aria-describedby="example-caption-4"></progress> - -<div class="text-center" id="example-caption-5">Reticulating splines… 100%</div> -<progress class="progress" value="100" max="100" aria-describedby="example-caption-5"></progress> -{% endexample %} - -## IE9 support - -Internet Explorer 9 doesn't support the HTML5 `<progress>` element, but we can work around that. - -{% example html %} -<div class="text-center" id="example-caption-6">Reticulating splines… 25%</div> -<progress class="progress" value="25" max="100" aria-describedby="example-caption-6"> - <div class="progress"> - <span class="progress-bar" style="width: 25%;"></span> - </div> -</progress> -{% endexample %} - -## Contextual alternatives - -Progress bars use some of the same button and alert classes for consistent styles. - -{% example html %} -<progress class="progress progress-success" value="25" max="100"></progress> -<progress class="progress progress-info" value="50" max="100"></progress> -<progress class="progress progress-warning" value="75" max="100"></progress> -<progress class="progress progress-danger" value="100" max="100"></progress> -{% endexample %} - -### Striped - -Uses a gradient to create a striped effect. - -{% example html %} -<progress class="progress progress-striped" value="10" max="100"></progress> -<progress class="progress progress-striped progress-success" value="25" max="100"></progress> -<progress class="progress progress-striped progress-info" value="50" max="100"></progress> -<progress class="progress progress-striped progress-warning" value="75" max="100"></progress> -<progress class="progress progress-striped progress-danger" value="100" max="100"></progress> -{% endexample %} - -### Animated stripes - -The striped gradient can also be animated. Add `.progress-animated` to `.progress` to animate the stripes right to left via CSS3 animations. - -**Animated progress bars do not work in IE9 and Opera 12** – as they don't support CSS3 animations – **nor in IE10+ and Microsoft Edge** – as they currently don't support CSS3 animations on the [`::-ms-fill` pseudo-element](https://msdn.microsoft.com/en-us/library/windows/apps/hh465757.aspx). - -<div class="bd-example"> - <progress class="progress progress-striped" value="25" max="100"></progress> - <button type="button" class="btn btn-secondary bd-activate-animated-progressbar" data-toggle="button" aria-pressed="false" autocomplete="off"> - Toggle animation - </button> -</div> - -{% highlight html %} -<progress class="progress progress-striped progress-animated" value="25" max="100"></progress> -{% endhighlight %} diff --git a/docs/components/scrollspy.md b/docs/components/scrollspy.md deleted file mode 100644 index 74829267e..000000000 --- a/docs/components/scrollspy.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -layout: docs -title: Scrollspy -description: Documentation and examples for the scrollspy plugin with Bootstrap's navigation components. -group: components ---- - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - -## Example in navbar - -The ScrollSpy plugin is for automatically updating nav targets based on scroll position. Scroll the area below the navbar and watch the active class change. The dropdown sub items will be highlighted as well. - -<div class="bd-example"> - <nav id="navbar-example2" class="navbar navbar-light bg-faded"> - <a class="navbar-brand" href="#">Navbar</a> - <ul class="nav nav-pills"> - <li class="nav-item"><a class="nav-link" href="#fat">@fat</a></li> - <li class="nav-item"><a class="nav-link" href="#mdo">@mdo</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="#one">one</a> - <a class="dropdown-item" href="#two">two</a> - <div role="separator" class="dropdown-divider"></div> - <a class="dropdown-item" href="#three">three</a> - </div> - </li> - </ul> - </nav> - <div data-spy="scroll" data-target="#navbar-example2" data-offset="0" class="scrollspy-example"> - <h4 id="fat">@fat</h4> - <p>Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.</p> - <h4 id="mdo">@mdo</h4> - <p>Veniam marfa mustache skateboard, adipisicing fugiat velit pitchfork beard. Freegan beard aliqua cupidatat mcsweeney's vero. Cupidatat four loko nisi, ea helvetica nulla carles. Tattooed cosby sweater food truck, mcsweeney's quis non freegan vinyl. Lo-fi wes anderson +1 sartorial. Carles non aesthetic exercitation quis gentrify. Brooklyn adipisicing craft beer vice keytar deserunt.</p> - <h4 id="one">one</h4> - <p>Occaecat commodo aliqua delectus. Fap craft beer deserunt skateboard ea. Lomo bicycle rights adipisicing banh mi, velit ea sunt next level locavore single-origin coffee in magna veniam. High life id vinyl, echo park consequat quis aliquip banh mi pitchfork. Vero VHS est adipisicing. Consectetur nisi DIY minim messenger bag. Cred ex in, sustainable delectus consectetur fanny pack iphone.</p> - <h4 id="two">two</h4> - <p>In incididunt echo park, officia deserunt mcsweeney's proident master cleanse thundercats sapiente veniam. Excepteur VHS elit, proident shoreditch +1 biodiesel laborum craft beer. Single-origin coffee wayfarers irure four loko, cupidatat terry richardson master cleanse. Assumenda you probably haven't heard of them art party fanny pack, tattooed nulla cardigan tempor ad. Proident wolf nesciunt sartorial keffiyeh eu banh mi sustainable. Elit wolf voluptate, lo-fi ea portland before they sold out four loko. Locavore enim nostrud mlkshk brooklyn nesciunt.</p> - <h4 id="three">three</h4> - <p>Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.</p> - <p>Keytar twee blog, culpa messenger bag marfa whatever delectus food truck. Sapiente synth id assumenda. Locavore sed helvetica cliche irony, thundercats you probably haven't heard of them consequat hoodie gluten-free lo-fi fap aliquip. Labore elit placeat before they sold out, terry richardson proident brunch nesciunt quis cosby sweater pariatur keffiyeh ut helvetica artisan. Cardigan craft beer seitan readymade velit. VHS chambray laboris tempor veniam. Anim mollit minim commodo ullamco thundercats. - </p> - </div> -</div> - - -## Usage - -### Requires Bootstrap nav - -Scrollspy currently requires the use of a [Bootstrap nav component]({{ site.baseurl }}/components/navs/) for proper highlighting of active links. - -### Requires relative positioning - -No matter the implementation method, scrollspy requires the use of `position: relative;` on the element you're spying on. In most cases this is the `<body>`. When scrollspying on elements other than the `<body>`, be sure to have a `height` set and `overflow-y: scroll;` applied. - -### Via data attributes - -To easily add scrollspy behavior to your topbar navigation, add `data-spy="scroll"` to the element you want to spy on (most typically this would be the `<body>`). Then add the `data-target` attribute with the ID or class of the parent element of any Bootstrap `.nav` component. - -{% highlight css %} -body { - position: relative; -} -{% endhighlight %} - -{% highlight html %} -<body data-spy="scroll" data-target="#navbar-example"> - ... - <div id="navbar-example"> - <ul class="nav nav-tabs" role="tablist"> - ... - </ul> - </div> - ... -</body> -{% endhighlight %} - -### Via JavaScript - -After adding `position: relative;` in your CSS, call the scrollspy via JavaScript: - -{% highlight js %} -$('body').scrollspy({ target: '#navbar-example' }) -{% endhighlight %} - -{% callout danger %} -#### Resolvable ID targets required - -Navbar links must have resolvable id targets. For example, a `<a href="#home">home</a>` must correspond to something in the DOM like `<div id="home"></div>`. -{% endcallout %} - -{% callout info %} -#### Non-`:visible` target elements ignored - -Target elements that are not [`:visible` according to jQuery](https://api.jquery.com/visible-selector/) will be ignored and their corresponding nav items will never be highlighted. -{% endcallout %} - -### Methods - -#### `.scrollspy('refresh')` - -When using scrollspy in conjunction with adding or removing of elements from the DOM, you'll need to call the refresh method like so: - -{% highlight js %} -$('[data-spy="scroll"]').each(function () { - var $spy = $(this).scrollspy('refresh') -}) -{% endhighlight %} - - -### Options - -Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-offset=""`. - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 100px;">Name</th> - <th style="width: 100px;">Type</th> - <th style="width: 50px;">Default</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>offset</td> - <td>number</td> - <td>10</td> - <td>Pixels to offset from top when calculating position of scroll.</td> - </tr> - </tbody> - </table> -</div> - -### Events - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>activate.bs.scrollspy</td> - <td>This event fires whenever a new item becomes activated by the scrollspy.</td> - </tr> - </tbody> - </table> -</div> -{% highlight js %} -$('#myScrollspy').on('activate.bs.scrollspy', function () { - // do something… -}) -{% endhighlight %} diff --git a/docs/components/tooltips.md b/docs/components/tooltips.md deleted file mode 100644 index 31fb2c1c7..000000000 --- a/docs/components/tooltips.md +++ /dev/null @@ -1,322 +0,0 @@ ---- -layout: docs -title: Tooltips -description: Documentation and examples for adding custom Bootstrap tooltips with CSS and JavaScript. -group: components ---- - -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: - -- Tooltips rely on the 3rd party library [Tether](http://tether.io/) for positioning. You must include [tether.min.js](https://github.com/HubSpot/tether/blob/master/dist/js/tether.min.js) before bootstrap.js in order for tooltips to work! -- Tooltips are opt-in for performance reasons, so **you must initialize them yourself**. -- Tooltips with zero-length titles are never displayed. -- Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc). -- Triggering tooltips on hidden elements will not work. -- Tooltips for `.disabled` or `disabled` elements must be triggered on a wrapper element. -- When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior. - -Got all that? Great, let's see how they work with some examples. - -## Example: Enable tooltips everywhere - -One way to initialize all tooltips on a page would be to select them by their `data-toggle` attribute: - -{% highlight js %} -$(function () { - $('[data-toggle="tooltip"]').tooltip() -}) -{% endhighlight %} - -## Examples - -Hover over the links below to see tooltips: - -<div class="bd-example tooltip-demo"> - <p class="muted">Tight pants next level keffiyeh <a href="#" data-toggle="tooltip" title="Default tooltip">you probably</a> haven't heard of them. Photo booth beard raw denim letterpress vegan messenger bag stumptown. Farm-to-table seitan, mcsweeney's fixie sustainable quinoa 8-bit american apparel <a href="#" data-toggle="tooltip" title="Another tooltip">have a</a> terry richardson vinyl chambray. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, four loko mcsweeney's cleanse vegan chambray. A really ironic artisan <a href="#" data-toggle="tooltip" title="Another one here too">whatever keytar</a>, scenester farm-to-table banksy Austin <a href="#" data-toggle="tooltip" title="The last tip!">twitter handle</a> freegan cred raw denim single-origin coffee viral. - </p> -</div> - -### Static demo - -Four options are available: top, right, bottom, and left aligned. - -<div class="bd-example bd-example-tooltip-static"> - <div class="tooltip tooltip-top" role="tooltip"> - <div class="tooltip-inner"> - Tooltip on the top - </div> - </div> - <div class="tooltip tooltip-right" role="tooltip"> - <div class="tooltip-inner"> - Tooltip on the right - </div> - </div> - <div class="tooltip tooltip-bottom" role="tooltip"> - <div class="tooltip-inner"> - Tooltip on the bottom - </div> - </div> - <div class="tooltip tooltip-left" role="tooltip"> - <div class="tooltip-inner"> - Tooltip on the left - </div> - </div> -</div> - -### Interactive demo - -Hover over the buttons below to see their tooltips. - -<div class="bd-example tooltip-demo"> - <div class="bd-example-tooltips"> - <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button> - <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button> - <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button> - <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button> - <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">Tooltip with HTML</button> - </div> -</div> - -{% highlight html %} -<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top"> - Tooltip on top -</button> -<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right"> - Tooltip on right -</button> -<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom"> - Tooltip on bottom -</button> -<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left"> - Tooltip on left -</button> -{% endhighlight %} - -And with custom HTML added: - -{% highlight html %} -<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>"> - Tooltip with HTML -</button> -{% endhighlight %} - -## Usage - -The tooltip plugin generates content and markup on demand, and by default places tooltips after their trigger element. - -Trigger the tooltip via JavaScript: - -{% highlight js %} -$('#example').tooltip(options) -{% endhighlight %} - -### Markup - -The required markup for a tooltip is only a `data` attribute and `title` on the HTML element you wish to have a tooltip. The generated markup of a tooltip is rather simple, though it does require a position (by default, set to `top` by the plugin). - -{% callout warning %} -#### Making tooltips work for keyboard and assistive technology users - -You should only add tooltips to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). Although arbitrary HTML elements (such as `<span>`s) can be made focusable by adding the `tabindex="0"` attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users. In addition, most assistive technologies currently do not announce the tooltip in this situation. -{% endcallout %} - -{% highlight html %} -<!-- HTML to write --> -<a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a> - -<!-- Generated markup by the plugin --> -<div class="tooltip tooltip-top" role="tooltip"> - <div class="tooltip-arrow"></div> - <div class="tooltip-inner"> - Some tooltip text! - </div> -</div> -{% endhighlight %} - -### Options - -Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`. - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 100px;">Name</th> - <th style="width: 100px;">Type</th> - <th style="width: 50px;">Default</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>animation</td> - <td>boolean</td> - <td>true</td> - <td>Apply a CSS fade transition to the tooltip</td> - </tr> - <tr> - <td>container</td> - <td>string | element | false</td> - <td>false</td> - <td> - <p>Appends the tooltip to a specific element. Example: <code>container: 'body'</code>. This option is particularly useful in that it allows you to position the tooltip in the flow of the document near the triggering element - which will prevent the tooltip from floating away from the triggering element during a window resize.</p> - </td> - </tr> - <tr> - <td>delay</td> - <td>number | object</td> - <td>0</td> - <td> - <p>Delay showing and hiding the tooltip (ms) - does not apply to manual trigger type</p> - <p>If a number is supplied, delay is applied to both hide/show</p> - <p>Object structure is: <code>delay: { "show": 500, "hide": 100 }</code></p> - </td> - </tr> - <tr> - <td>html</td> - <td>boolean</td> - <td>false</td> - <td> - <p>Allow HTML in the tooltip.</p> - <p>If true, HTML tags in the tooltip's <code>title</code> will be rendered in the tooltip. If false, jQuery's <code>text</code> method will be used to insert content into the DOM.</p> - <p>Use text if you're worried about XSS attacks.</p> - </td> - </tr> - <tr> - <td>placement</td> - <td>string | function</td> - <td>'top'</td> - <td> - <p>How to position the tooltip - top | bottom | left | right.</p> - <p>When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The <code>this</code> context is set to the tooltip instance.</p> - </td> - </tr> - <tr> - <td>selector</td> - <td>string</td> - <td>false</td> - <td>If a selector is provided, popover objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added. See <a href="https://github.com/twbs/bootstrap/issues/4215">this</a> and <a href="https://jsbin.com/zopod/1/edit">an informative example</a>.</td> - </tr> - <tr> - <td>template</td> - <td>string</td> - <td><code>'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'</code></td> - <td> - <p>Base HTML to use when creating the tooltip.</p> - <p>The tooltip's <code>title</code> will be injected into the <code>.tooltip-inner</code>.</p> - <p><code>.tooltip-arrow</code> will become the tooltip's arrow.</p> - <p>The outermost wrapper element should have the <code>.tooltip</code> class.</p> - </td> - </tr> - <tr> - <td>title</td> - <td>string | element | function</td> - <td>''</td> - <td> - <p>Default title value if <code>title</code> attribute isn't present.</p> - <p>If a function is given, it will be called with its <code>this</code> reference set to the element that the tooltip is attached to.</p> - </td> - </tr> - <tr> - <td>trigger</td> - <td>string</td> - <td>'hover focus'</td> - <td>How tooltip is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. `manual` cannot be combined with any other trigger.</td> - </tr> - <tr> - <td>constraints</td> - <td>Array</td> - <td>[]</td> - <td>An array of constraints - passed through to Tether. For more information refer to Tether's <a href="http://tether.io/#constraints">constraint docs</a>.</td> - </tr> - <tr> - <td>offset</td> - <td>string</td> - <td>'0 0'</td> - <td>Offset of the popover relative to its target. For more information refer to Tether's <a href="http://tether.io/#constraints">offset docs</a>.</td> - </tr> - </tbody> - </table> -</div> - -{% callout info %} -#### Data attributes for individual tooltips - -Options for individual tooltips can alternatively be specified through the use of data attributes, as explained above. -{% endcallout %} - -### Methods - -#### `$().tooltip(options)` - -Attaches a tooltip handler to an element collection. - -#### `.tooltip('show')` - -Reveals an element's tooltip. **Returns to the caller before the tooltip has actually been shown** (i.e. before the `shown.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip. Tooltips with zero-length titles are never displayed. - -{% highlight js %}$('#element').tooltip('show'){% endhighlight %} - -#### `.tooltip('hide')` - -Hides an element's tooltip. **Returns to the caller before the tooltip has actually been hidden** (i.e. before the `hidden.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip. - -{% highlight js %}$('#element').tooltip('hide'){% endhighlight %} - -#### `.tooltip('toggle')` - -Toggles an element's tooltip. **Returns to the caller before the tooltip has actually been shown or hidden** (i.e. before the `shown.bs.tooltip` or `hidden.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip. - -{% highlight js %}$('#element').tooltip('toggle'){% endhighlight %} - -#### `.tooltip('dispose')` - -Hides and destroys an element's tooltip. Tooltips that use delegation (which are created using [the `selector` option](#options)) cannot be individually destroyed on descendant trigger elements. - -{% highlight js %}$('#element').tooltip('dispose'){% endhighlight %} - -### Events - -<div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>show.bs.tooltip</td> - <td>This event fires immediately when the <code>show</code> instance method is called.</td> - </tr> - <tr> - <td>shown.bs.tooltip</td> - <td>This event is fired when the tooltip has been made visible to the user (will wait for CSS transitions to complete).</td> - </tr> - <tr> - <td>hide.bs.tooltip</td> - <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td> - </tr> - <tr> - <td>hidden.bs.tooltip</td> - <td>This event is fired when the tooltip has finished being hidden from the user (will wait for CSS transitions to complete).</td> - </tr> - </tbody> - </table> -</div> - -{% highlight js %} -$('#myTooltip').on('hidden.bs.tooltip', function () { - // do something… -}) -{% endhighlight %} |
