mirror of
https://github.com/tenrok/bootstrap.git
synced 2026-05-24 14:04:09 +03:00
Merge branch 'v4-dev' into v4-docs-streamlined
This commit is contained in:
Mark Otto
@@ -1,61 +1,57 @@
|
||||
---
|
||||
layout: docs
|
||||
title: Accessibility
|
||||
description: Learn how Bootstrap supports common web standards for making sites that are accessibile to those using assistive technology.
|
||||
description: A brief overview of Bootstrap's features and limitations for the creation of accessible content.
|
||||
group: getting-started
|
||||
---
|
||||
|
||||
Bootstrap follows common web standards and—with minimal extra effort—can be used to create sites that are accessible to those using <abbr title="Assistive Technology" class="initialism">AT</abbr>.
|
||||
Bootstrap provides an easy-to-use framework of ready-made styles, layout tools, and interactive components, allowing developers to create web sites and applications that are visually appealing, functionally rich, and accessible out of the box.
|
||||
|
||||
## Contents
|
||||
|
||||
* Will be replaced with the ToC, excluding the "Contents" header
|
||||
{:toc}
|
||||
|
||||
## Component requirements
|
||||
## Overview and limitations
|
||||
|
||||
Some common HTML elements are always in need for basic accessibility enhancements through `role`s and Aria attributes. Below is a list of some of the most frequently used ones.
|
||||
The overall accessibility of any project built with Bootstrap depends in large part on the author's markup, additional styling, and scripting they've included. However, provided that these have been implemented correctly, it should be perfectly possible to create web sites and applications with Bootstrap that fulfill [<abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.0](https://www.w3.org/TR/WCAG20/) (A/AA/AAA), [Section 508](https://www.section508.gov/) and similar accessibility standards and requirements.
|
||||
|
||||
{% callout info %}
|
||||
**Heads up!** As we go through the alphas, we'll be moving more accessibility notes here with links to specific sections from other areas of the docs.
|
||||
{% endcallout %}
|
||||
### Structural markup
|
||||
|
||||
### Button groups
|
||||
Bootstrap's styling and layout can be applied to a wide range of markup structures. This documentation aims to provide developers with best practice examples to demonstrate the use of Bootstrap itself and illustrate appropriate semantic markup, including ways in which potential accessibility concerns can be addressed.
|
||||
|
||||
In order for assistive technologies–such as screen readers–to convey that a series of buttons is grouped, an appropriate `role` attribute needs to be provided. For button groups, this would be `role="group"`, while toolbars should have a `role="toolbar"`.
|
||||
### Interactive components
|
||||
|
||||
In addition, groups and toolbars should be given an explicit label, as most assistive technologies will otherwise not announce them, despite the presence of the correct `role` attribute. In the examples provided here, we use `aria-label`, but alternatives such as `aria-labelledby` can also be used.
|
||||
Bootstrap's interactive components—such as modal dialogs, dropdown menus and custom tooltips—are designed to work for touch, mouse and keyboard users. Through the use of relevant [<abbr title="Web Accessibility Initiative">WAI</abbr> <abbr title="Accessible Rich Internet Applications">ARIA</abbr>](https://www.w3.org/WAI/intro/aria) roles and attributes, these components should also be understandable and operable using assistive technologies (such as screen readers).
|
||||
|
||||
## Skip navigation
|
||||
Because Bootstrap's components are purposely designed to be fairly generic, authors may need to include further <abbr title="Accessible Rich Internet Applications">ARIA</abbr> roles and attributes, as well as JavaScript behavior, to more accurately convey the precise nature and functionality of their component. This is usually noted in the documentation.
|
||||
|
||||
If your navigation contains many links and comes before the main content in the DOM, add a `Skip to main content` link before the navigation (for a simple explanation, see this [A11Y Project article on skip navigation links](http://a11yproject.com/posts/skip-nav-links/)). Using the `.sr-only` class will visually hide the skip link, and the <code>.sr-only-focusable</code> class will ensure that the link becomes visible once focused (for sighted keyboard users).
|
||||
### Color contrast
|
||||
|
||||
{% callout danger %}
|
||||
Due to long-standing shortcomings/bugs in Internet Explorer (see this article on [in-page links and focus order](http://accessibleculture.org/articles/2010/05/in-page-links/)), you will need to make sure that the target of your skip link is at least programmatically focusable by adding `tabindex="-1"`.
|
||||
Most colors that currently make up Bootstrap's default palette—used throughout the framework for things such as button variations, alert variations, form validation indicators—lead to *insufficient* color contrast (below the recommended [WCAG 2.0 color contrast ratio of 4.5:1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html)) when used against a light background. Authors will need to manually modify/extend these default colors to ensure adequate color contrast ratios.
|
||||
|
||||
In addition, you may want to explicitly suppress a visible focus indication on the target (particularly as Chrome currently also sets focus on elements with `tabindex="-1"` when they are clicked with the mouse) with `#content:focus { outline: none; }`.
|
||||
### Visually hidden content
|
||||
|
||||
Note that this bug will also affect any other in-page links your site may be using, rendering them useless for keyboard users. You may consider adding a similar stop-gap fix to all other named anchors / fragment identifiers that act as link targets.
|
||||
{% endcallout %}
|
||||
Content which should be visually hidden, but remain accessible to assistive technologies such as screen readers, can be styled using the `.sr-only` class. This can be useful in situations where additional visual information or cues (such as meaning denoted through the use of color) need to also be conveyed to non-visual users.
|
||||
|
||||
{% highlight html %}
|
||||
<body>
|
||||
<a href="#content" class="sr-only sr-only-focusable">Skip to main content</a>
|
||||
...
|
||||
<div class="container" id="content" tabindex="-1">
|
||||
<!-- The main page content -->
|
||||
</div>
|
||||
</body>
|
||||
<p class="text-danger">
|
||||
<span class=".sr-only">Danger: </span>
|
||||
This action is not reversible
|
||||
</p>
|
||||
{% endhighlight %}
|
||||
|
||||
## Nested headings
|
||||
For visually hidden interactive controls, such as traditional "skip" links, `.sr-only` can be combined with the `.sr-only-focusable` class. This will ensure that the control becomes visible once focused (for sighted keyboard users).
|
||||
|
||||
When nesting headings (`<h1>` - `<h6>`), your primary document header should be an `<h1>`. Subsequent headings should make logical use of `<h2>` - `<h6>` such that screen readers can construct a table of contents for your pages.
|
||||
|
||||
Learn more at [HTML CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/Standards/Section508/) and [Penn State's Accessability](http://accessibility.psu.edu/headings/).
|
||||
{% highlight html %}
|
||||
<a class="sr-only sr-only-focusable" href="#content">Skip to main content</a>
|
||||
{% endhighlight %}
|
||||
|
||||
## Additional resources
|
||||
|
||||
- ["HTML Codesniffer" bookmarklet for identifying accessibility issues](https://github.com/squizlabs/HTML_CodeSniffer)
|
||||
- [Web Content Accessibility Guidelines (WCAG) 2.0](https://www.w3.org/TR/WCAG20/)
|
||||
- [The A11Y Project](http://a11yproject.com/)
|
||||
- [MDN accessibility documentation](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
|
||||
- [Tenon.io Accessibility Checker](https://tenon.io/)
|
||||
- [Colour Contrast Analyser (CCA)](https://www.paciellogroup.com/resources/contrastanalyser/)
|
||||
- ["HTML Codesniffer" bookmarklet for identifying accessibility issues](https://github.com/squizlabs/HTML_CodeSniffer)
|
||||
|
||||
@@ -22,161 +22,102 @@ Alternative browsers which use the latest version of WebKit, Blink, or Gecko, wh
|
||||
|
||||
Generally speaking, Bootstrap supports the latest versions of each major platform's default browsers. Note that proxy browsers (such as Opera Mini, Opera Mobile's Turbo mode, UC Browser Mini, Amazon Silk) are not supported.
|
||||
|
||||
<div class="table-responsive">
|
||||
<table class="table table-bordered table-striped">
|
||||
<thead>
|
||||
<tr>
|
||||
<td></td>
|
||||
<th>Chrome</th>
|
||||
<th>Firefox</th>
|
||||
<th>Safari</th>
|
||||
<th>Android Browser & WebView</th>
|
||||
<th>Microsoft Edge</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th scope="row">Android</th>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-success">Android v5.0+ supported</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th scope="row">iOS</th>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th scope="row">Windows 10 Mobile</th>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-success">Supported</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<table class="table table-bordered table-striped table-responsive">
|
||||
<thead>
|
||||
<tr>
|
||||
<td></td>
|
||||
<th>Chrome</th>
|
||||
<th>Firefox</th>
|
||||
<th>Safari</th>
|
||||
<th>Android Browser & WebView</th>
|
||||
<th>Microsoft Edge</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th scope="row">Android</th>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-success">Android v5.0+ supported</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th scope="row">iOS</th>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th scope="row">Windows 10 Mobile</th>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-success">Supported</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
### Desktop browsers
|
||||
|
||||
Similarly, the latest versions of most desktop browsers are supported.
|
||||
|
||||
<div class="table-responsive">
|
||||
<table class="table table-bordered table-striped">
|
||||
<thead>
|
||||
<tr>
|
||||
<td></td>
|
||||
<th>Chrome</th>
|
||||
<th>Firefox</th>
|
||||
<th>Internet Explorer</th>
|
||||
<th>Microsoft Edge</th>
|
||||
<th>Opera</th>
|
||||
<th>Safari</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th scope="row">Mac</th>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th scope="row">Windows</th>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported, IE10+</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-danger">Not supported</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<table class="table table-bordered table-striped table-responsive">
|
||||
<thead>
|
||||
<tr>
|
||||
<td></td>
|
||||
<th>Chrome</th>
|
||||
<th>Firefox</th>
|
||||
<th>Internet Explorer</th>
|
||||
<th>Microsoft Edge</th>
|
||||
<th>Opera</th>
|
||||
<th>Safari</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th scope="row">Mac</th>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-muted">N/A</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th scope="row">Windows</th>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported, IE10+</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
<td class="text-danger">Not supported</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
For Firefox, in addition to the latest normal stable release, we also support the latest [Extended Support Release (ESR)](https://www.mozilla.org/en-US/firefox/organizations/faq/) version of Firefox.
|
||||
|
||||
Unofficially, Bootstrap should look and behave well enough in Chromium and Chrome for Linux, Firefox for Linux, and Internet Explorer 9 and below, though they are not officially supported.
|
||||
Unofficially, Bootstrap should look and behave well enough in Chromium and Chrome for Linux, Firefox for Linux, and Internet Explorer 9, though they are not officially supported.
|
||||
|
||||
For a list of some of the browser bugs that Bootstrap has to grapple with, see our [Wall of browser bugs]({{ site.baseurl }}/browser-bugs/).
|
||||
|
||||
## Internet Explorer
|
||||
|
||||
Internet Explorer 10+ is supported, however, IE9 down is not. Please be aware that some CSS3 properties and HTML5 elements are not fully supported.
|
||||
Internet Explorer 10+ is supported; IE9 and down is not. Please be aware that some CSS3 properties and HTML5 elements are not fully supported in IE10, or require prefixed properties for full functionality. Visit [Can I use...](http://caniuse.com/) for details on browser support of CSS3 and HTML5 features.
|
||||
|
||||
<div class="table-responsive">
|
||||
<table class="table table-bordered table-striped">
|
||||
<thead>
|
||||
<tr>
|
||||
<th scope="col">Feature</th>
|
||||
<th scope="col">Internet Explorer 9</th>
|
||||
<th scope="col">Internet Explorer 10</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th scope="row"><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/transition"><code>transition</code></a></th>
|
||||
<td class="text-danger">Not supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th scope="row"><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#attr-placeholder"><code>placeholder</code></a></th>
|
||||
<td class="text-danger">Not supported</td>
|
||||
<td class="text-success">Supported</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th scope="row"><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Using_CSS_flexible_boxes">Flexbox</a></th>
|
||||
<td class="text-danger">Not supported</td>
|
||||
<td class="text-warning">Partially supported, with <code>-ms</code> prefix<br><a href="http://caniuse.com/#feat=flexbox">See <em>Can I use</em> for details</a></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
Visit [Can I use...](http://caniuse.com/) for details on browser support of CSS3 and HTML5 features.
|
||||
|
||||
## Supporting Internet Explorer 8-9
|
||||
|
||||
As of v4, Bootstrap no longer supports IE8 or IE9. **If you require IE8-9 support, we recommend you use Bootstrap 3.** It's still supported by our team for bugfixes and documentation changes, but no new features will be added to it.
|
||||
|
||||
Alternatively, you may add some third party JavaScript to backfill support for IE8-9 to Bootstrap 4. You'll need the following:
|
||||
|
||||
* [The HTML5 shiv](https://en.wikipedia.org/wiki/HTML5_Shiv)
|
||||
* [Respond.js](https://github.com/scottjehl/Respond)
|
||||
* [Rem unit polyfill](https://github.com/chuckcarpenter/REM-unit-polyfill)
|
||||
|
||||
No support will be provided for this, though you may find some help from the community in [our Slack channel]({{ site.slack }}).
|
||||
|
||||
## IE Compatibility modes
|
||||
|
||||
Bootstrap is not supported in the old Internet Explorer compatibility modes. To be sure you're using the latest rendering mode for IE, consider including the appropriate `<meta>` tag in your pages:
|
||||
|
||||
{% highlight html %}
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
{% endhighlight %}
|
||||
|
||||
Confirm the document mode by opening the debugging tools: press <kbd>F12</kbd> and check the "Document Mode".
|
||||
|
||||
This tag is included in all of Bootstrap's documentation and examples to ensure the best rendering possible in each supported version of Internet Explorer.
|
||||
|
||||
See [this StackOverflow question](https://stackoverflow.com/questions/6771258/what-does-meta-http-equiv-x-ua-compatible-content-ie-edge-do) for more information.
|
||||
**If you require IE8-9 support, use Bootstrap 3.** It's the most stable version of our code and is still supported by our team for critical bugfixes and documentation changes. However, no new features will be added to it.
|
||||
|
||||
## Internet Explorer 10 in Windows Phone 8
|
||||
|
||||
Internet Explorer 10 in Windows Phone 8 versions older than [Update 3 (a.k.a. GDR3)](https://blogs.windows.com/buildingapps/2013/10/14/introducing-windows-phone-preview-for-developers/) doesn't differentiate **device width** from **viewport width** in `@-ms-viewport` at-rules, and thus doesn't properly apply the media queries in Bootstrap's CSS. To address this, you'll need to **include the following JavaScript to work around the bug**.
|
||||
|
||||
{% highlight js %}
|
||||
// Copyright 2014-2015 The Bootstrap Authors
|
||||
// Copyright 2014-2015 Twitter, Inc.
|
||||
// Copyright 2014-2017 The Bootstrap Authors
|
||||
// Copyright 2014-2017 Twitter, Inc.
|
||||
// Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
|
||||
if (navigator.userAgent.match(/IEMobile\/10\.0/)) {
|
||||
var msViewportStyle = document.createElement('style')
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Details on how to use Bootstrap's included build tools to compile s
|
||||
group: getting-started
|
||||
---
|
||||
|
||||
Bootstrap uses [Grunt](http://gruntjs.com) for its CSS and JavaScript build system and Jekyll for the written documentation. Our Gruntfile includes convenient methods for working with the framework, including compiling code, running tests, and more.
|
||||
Bootstrap uses [NPM scripts](https://docs.npmjs.com/misc/scripts) for its build system. Our [package.json](https://github.com/twbs/bootstrap/blob/v4-dev/package.json) includes convenient methods for working with the framework, including compiling code, running tests, and more.
|
||||
|
||||
## Contents
|
||||
|
||||
@@ -14,62 +14,46 @@ Bootstrap uses [Grunt](http://gruntjs.com) for its CSS and JavaScript build syst
|
||||
|
||||
## Tooling setup
|
||||
|
||||
To use our Gruntfile and run our documentation locally, you'll need a copy of Bootstrap's source files, Node, and Grunt. Follow these steps and you should be ready to rock:
|
||||
To use our build system and run our documentation locally, you'll need a copy of Bootstrap's source files and Node. Follow these steps and you should be ready to rock:
|
||||
|
||||
1. [Download and install Node](https://nodejs.org/download/), which we use to manage our dependencies.
|
||||
2. Install the Grunt command line tools, `grunt-cli`, with `npm install -g grunt-cli`.
|
||||
3. Navigate to the root `/bootstrap` directory and run `npm install` to install our local dependencies listed in [package.json](https://github.com/twbs/bootstrap/blob/master/package.json).
|
||||
2. Navigate to the root `/bootstrap` directory and run `npm install` to install our local dependencies listed in [package.json](https://github.com/twbs/bootstrap/blob/master/package.json).
|
||||
4. [Install Ruby][install-ruby], install [Bundler][gembundler] with `gem install bundler`, and finally run `bundle install`. This will install all Ruby dependencies, such as Jekyll and plugins.
|
||||
- **Windows users:** Read [this unofficial guide](http://jekyll-windows.juthilo.com/) to get Jekyll up and running without problems.
|
||||
|
||||
When completed, you'll be able to run the various Grunt commands provided from the command line.
|
||||
When completed, you'll be able to run the various commands provided from the command line.
|
||||
|
||||
[install-ruby]: https://www.ruby-lang.org/en/documentation/installation/
|
||||
[gembundler]: https://bundler.io/
|
||||
|
||||
## Using Grunt
|
||||
## Using NPM scripts
|
||||
|
||||
Our Gruntfile includes the following commands and tasks:
|
||||
Our [package.json](https://github.com/twbs/bootstrap/blob/master/package.json) includes the following commands and tasks:
|
||||
|
||||
| Task | Description |
|
||||
| --- | --- |
|
||||
| `grunt` | Run `grunt` to run tests locally and compile the CSS and JavaScript into `/dist`. **Uses [Sass](http://sass-lang.com/), [Autoprefixer][autoprefixer], and [UglifyJS](http://lisperator.net/uglifyjs/).** |
|
||||
| `grunt dist` | `grunt dist` creates the `/dist` directory with compiled files. **Uses [Sass](http://sass-lang.com/), [Autoprefixer][autoprefixer], and [UglifyJS](http://lisperator.net/uglifyjs/).** |
|
||||
| `grunt test` | Runs [scss-lint](https://github.com/brigade/scss-lint), [ESLint](http://eslint.org/) and [QUnit](https://qunitjs.com/) tests headlessly in [PhantomJS](http://phantomjs.org/) (used for CI). |
|
||||
| `grunt docs` | Builds and tests CSS, JavaScript, and other assets which are used when running the documentation locally via `jekyll serve`. |
|
||||
| `grunt watch` | This is a convenience method for watching just Sass files and automatically building them whenever you save. |
|
||||
|
||||
## Switching Sass compilers
|
||||
|
||||
Bootstrap will be compiled with [libsass][libsass] by default, but you can opt into traditional Ruby Sass by setting the `TWBS_SASS` environment variable. Two options are supported:
|
||||
|
||||
* `libsass` (default) to use [libsass][libsass] via [grunt-sass][grunt-sass].
|
||||
* `sass` to use [Ruby Sass][ruby-sass] via [grunt-contrib-sass][grunt-contrib-sass].
|
||||
|
||||
For example, run `TWBS_SASS=sass grunt` to test and build Bootstrap with Ruby Sass.
|
||||
| `npm test` | Run `npm test` to run tests locally and compile the CSS and JavaScript into `/dist`. **Uses [Sass](http://sass-lang.com/), [Autoprefixer][autoprefixer], and [UglifyJS](http://lisperator.net/uglifyjs/).** |
|
||||
| `npm run dist` | `npm run dist` creates the `/dist` directory with compiled files. **Uses [Sass](http://sass-lang.com/), [Autoprefixer][autoprefixer], and [UglifyJS](http://lisperator.net/uglifyjs/).** |
|
||||
| `npm run docs` | Builds and tests CSS, JavaScript, and other assets which are used when running the documentation locally via `npm run docs-serve`. |
|
||||
|
||||
## Autoprefixer
|
||||
|
||||
Bootstrap uses [Autoprefixer][autoprefixer] (included in our Gruntfile and build process) to automatically add vendor prefixes to some CSS properties at build time. Doing so saves us time and code by allowing us to write key parts of our CSS a single time while eliminating the need for vendor mixins like those found in v3.
|
||||
Bootstrap uses [Autoprefixer][autoprefixer] (included in our build process) to automatically add vendor prefixes to some CSS properties at build time. Doing so saves us time and code by allowing us to write key parts of our CSS a single time while eliminating the need for vendor mixins like those found in v3.
|
||||
|
||||
We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [`/grunt/postcss.js`](https://github.com/twbs/bootstrap/blob/master/grunt/postcss.js) for details.
|
||||
We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [`/build/postcss.config.js`](https://github.com/twbs/bootstrap/blob/v4-dev/build/postcss.config.js) for details.
|
||||
|
||||
## Local documentation
|
||||
|
||||
Running our documentation locally requires the use of Jekyll, a decently flexible static site generator that provides us: basic includes, Markdown-based files, templates, and more. Here's how to get it started:
|
||||
|
||||
1. Run through the [tooling setup](#tooling-setup) above to install Jekyll (the site builder) and other Ruby dependencies with `bundle install`.
|
||||
2. From the root `/bootstrap` directory, run `bundle exec jekyll serve` in the command line.
|
||||
2. From the root `/bootstrap` directory, run `npm run docs-serve` in the command line.
|
||||
3. Open <http://localhost:9001> in your browser, and voilà.
|
||||
|
||||
Learn more about using Jekyll by reading its [documentation](https://jekyllrb.com/docs/home/).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun `npm install`.
|
||||
Should you encounter problems with installing dependencies, uninstall all previous dependency versions (global and local). Then, rerun `npm install`.
|
||||
|
||||
[ruby-sass]: https://github.com/sass/sass
|
||||
[grunt-contrib-sass]: https://github.com/gruntjs/grunt-contrib-sass
|
||||
[libsass]: https://github.com/sass/libsass
|
||||
[grunt-sass]: https://github.com/sindresorhus/grunt-sass
|
||||
[autoprefixer]: https://github.com/postcss/autoprefixer
|
||||
|
||||
@@ -38,13 +38,9 @@ Skip the download and use the Bootstrap CDN to deliver Bootstrap's compiled CSS
|
||||
|
||||
Pull in Bootstrap's **source files** into nearly any project with some of the most popular package managers. No matter the package manager, Bootstrap will **require a Sass compiler, [Autoprefixer](https://github.com/postcss/autoprefixer), and [postcss-flexbugs-fixes](https://github.com/luisrudge/postcss-flexbugs-fixes)** for a setup that matches our official compiled versions.
|
||||
|
||||
{% callout warning %}
|
||||
**Heads up!** Not all package managers have the v4 alpha published yet, but we should have them up shortly!
|
||||
{% endcallout %}
|
||||
|
||||
### npm
|
||||
|
||||
Install Bootstrap in your Node powered apps with [the npm package](https://www.npmjs.org/package/bootstrap):
|
||||
Install Bootstrap in your Node powered apps with [the npm package](https://www.npmjs.com/package/bootstrap):
|
||||
|
||||
{% highlight bash %}
|
||||
npm install bootstrap@{{ site.current_version }}
|
||||
@@ -62,13 +58,13 @@ Bootstrap's `package.json` contains some additional metadata under the following
|
||||
Install Bootstrap in your Ruby apps using [Bundler](https://bundler.io/) (**recommended**) and [RubyGems](https://rubygems.org/) by adding the following line to your [`Gemfile`](https://bundler.io/gemfile.html):
|
||||
|
||||
{% highlight ruby %}
|
||||
gem 'bootstrap', '~> 4.0.0.alpha5'
|
||||
gem 'bootstrap', '~> 4.0.0.alpha6'
|
||||
{% endhighlight %}
|
||||
|
||||
Alternatively, if you're not using Bundler, you can install the gem by running this command:
|
||||
|
||||
{% highlight bash %}
|
||||
gem install bootstrap -v 4.0.0.alpha5
|
||||
gem install bootstrap -v 4.0.0.alpha6
|
||||
{% endhighlight %}
|
||||
|
||||
[See the gem's README](https://github.com/twbs/bootstrap-rubygem/blob/master/README.md) for further details.
|
||||
|
||||
@@ -28,11 +28,11 @@ Copy-paste the stylesheet `<link>` into your `<head>` before all other styleshee
|
||||
<link rel="stylesheet" href="{{ site.cdn.css }}" integrity="{{ site.cdn.css_hash }}" crossorigin="anonymous">
|
||||
{% endhighlight %}
|
||||
|
||||
Add our JavaScript plugins, jQuery, and Tether near the end of your pages, right before the closing `</body>` tag. Be sure to place jQuery and Tether first, as our code depends on them.
|
||||
Add our JavaScript plugins, jQuery, and Popper.js near the end of your pages, right before the closing `</body>` tag. Be sure to place jQuery and Popper.js first, as our code depends on them. While we use [jQuery's slim build](https://blog.jquery.com/2016/06/09/jquery-3-0-final-released/) in our docs, the full version is also supported.
|
||||
|
||||
{% highlight html %}
|
||||
<script src="{{ site.cdn.jquery }}" integrity="{{ site.cdn.jquery_hash }}" crossorigin="anonymous"></script>
|
||||
<script src="{{ site.cdn.tether }}" integrity="{{ site.cdn.tether_hash }}" crossorigin="anonymous"></script>
|
||||
<script src="{{ site.cdn.popper }}" integrity="{{ site.cdn.popper_hash }}" crossorigin="anonymous"></script>
|
||||
<script src="{{ site.cdn.js }}" integrity="{{ site.cdn.js_hash }}" crossorigin="anonymous"></script>
|
||||
{% endhighlight %}
|
||||
|
||||
@@ -40,22 +40,15 @@ And that's it—you're on your way to a fully Bootstrapped site. If you're at al
|
||||
|
||||
## Starter template
|
||||
|
||||
Be sure to have your pages set up with the latest design and development standards. That means:
|
||||
|
||||
* Using an HTML5 doctype
|
||||
* Forcing Internet Explorer to use its latest rendering mode ([read more](https://stackoverflow.com/questions/6771258/what-does-meta-http-equiv-x-ua-compatible-content-ie-edge-do))
|
||||
* And, utilizing the viewport meta tag.
|
||||
|
||||
Put it all together and your pages should look like this:
|
||||
Be sure to have your pages set up with the latest design and development standards. That means using an HTML5 doctype and including a viewport meta tag for proper responsive behaviors. Put it all together and your pages should look like this:
|
||||
|
||||
{% highlight html %}
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- Required meta tags always come first -->
|
||||
<!-- Required meta tags -->
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
|
||||
<meta http-equiv="x-ua-compatible" content="ie=edge">
|
||||
|
||||
<!-- Bootstrap CSS -->
|
||||
<link rel="stylesheet" href="{{ site.cdn.css }}" integrity="{{ site.cdn.css_hash }}" crossorigin="anonymous">
|
||||
@@ -63,9 +56,9 @@ Put it all together and your pages should look like this:
|
||||
<body>
|
||||
<h1>Hello, world!</h1>
|
||||
|
||||
<!-- jQuery first, then Tether, then Bootstrap JS. -->
|
||||
<!-- jQuery first, then Popper.js, then Bootstrap JS. -->
|
||||
<script src="{{ site.cdn.jquery }}" integrity="{{ site.cdn.jquery_hash }}" crossorigin="anonymous"></script>
|
||||
<script src="{{ site.cdn.tether }}" integrity="{{ site.cdn.tether_hash }}" crossorigin="anonymous"></script>
|
||||
<script src="{{ site.cdn.popper }}" integrity="{{ site.cdn.popper_hash }}" crossorigin="anonymous"></script>
|
||||
<script src="{{ site.cdn.js }}" integrity="{{ site.cdn.js_hash }}" crossorigin="anonymous"></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -106,9 +99,7 @@ On the rare occasion you need to override it, use something like the following:
|
||||
|
||||
{% highlight scss %}
|
||||
.selector-for-some-widget {
|
||||
-webkit-box-sizing: content-box;
|
||||
-moz-box-sizing: content-box;
|
||||
box-sizing: content-box;
|
||||
box-sizing: content-box;
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
@@ -116,9 +107,9 @@ With the above snippet, nested elements—including generated content via `:befo
|
||||
|
||||
Learn more about [box model and sizing at CSS Tricks](https://css-tricks.com/box-sizing/).
|
||||
|
||||
### Normalize.css
|
||||
### Reboot
|
||||
|
||||
For improved cross-browser rendering, we use [Normalize.css](https://necolas.github.io/normalize.css/) to correct small inconsistencies across browsers and devices. We further build on this with our own, slightly more opinionated styles with [Reboot]({{ site.baseurl }}/content/reboot/).
|
||||
For improved cross-browser rendering, we use [Reboot]({{ site.baseurl }}/content/reboot/) to correct inconsistencies across browsers and devices while providing slightly more opinionated resets to common HTML elements.
|
||||
|
||||
## Community
|
||||
|
||||
|
||||
@@ -36,6 +36,18 @@ Alternatively, to target a specific plugin, just include the plugin's name as a
|
||||
$(document).off('.alert.data-api')
|
||||
{% endhighlight %}
|
||||
|
||||
## Events
|
||||
|
||||
Bootstrap provides custom events for most plugins' unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. `show`) is triggered at the start of an event, and its past participle form (ex. `shown`) is triggered on the completion of an action.
|
||||
|
||||
All infinitive events provide [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) functionality. This provides the ability to stop the execution of an action before it starts.
|
||||
|
||||
{% highlight js %}
|
||||
$('#myModal').on('show.bs.modal', function (e) {
|
||||
if (!data) return e.preventDefault() // stops modal from being shown
|
||||
})
|
||||
{% endhighlight %}
|
||||
|
||||
## Programmatic API
|
||||
|
||||
We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon.
|
||||
@@ -54,11 +66,32 @@ $('#myModal').modal('show') // initializes and invokes show immed
|
||||
|
||||
Each plugin also exposes its raw constructor on a `Constructor` property: `$.fn.popover.Constructor`. If you'd like to get a particular plugin instance, retrieve it directly from an element: `$('[rel="popover"]').data('popover')`.
|
||||
|
||||
### Asynchronous functions and transitions
|
||||
|
||||
All programmatic API methods are **asynchronous** and returns to the caller once the transition is started but **before it ends**.
|
||||
|
||||
In order to execute an action once the transition is complete, you can listen to the corresponding event.
|
||||
{% highlight js %}
|
||||
$('#myCollapse').on('shown.bs.collapse', function (e) {
|
||||
// Action to execute once the collapsible area is expanded
|
||||
})
|
||||
{% endhighlight %}
|
||||
|
||||
In addition a method call on a **transitioning component will be ignored**.
|
||||
{% highlight js %}
|
||||
$('#myCarousel').on('slid.bs.carousel', function (e) {
|
||||
$('#myCarousel').carousel('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
|
||||
})
|
||||
|
||||
$('#myCarousel').carousel('1') // Will start sliding to the slide 1 and returns to the caller
|
||||
$('#myCarousel').carousel('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!
|
||||
{% endhighlight %}
|
||||
|
||||
### Default settings
|
||||
You can change the default settings for a plugin by modifying the plugin's `Constructor.DEFAULTS` object:
|
||||
You can change the default settings for a plugin by modifying the plugin's `Constructor.Default` object:
|
||||
|
||||
{% highlight js %}
|
||||
$.fn.modal.Constructor.DEFAULTS.keyboard = false // changes default for the modal plugin's `keyboard` option to false
|
||||
$.fn.modal.Constructor.Default.keyboard = false // changes default for the modal plugin's `keyboard` option to false
|
||||
{% endhighlight %}
|
||||
|
||||
## No conflict
|
||||
@@ -70,18 +103,6 @@ var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previous
|
||||
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
|
||||
{% endhighlight %}
|
||||
|
||||
## Events
|
||||
|
||||
Bootstrap provides custom events for most plugins' unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. `show`) is triggered at the start of an event, and its past participle form (ex. `shown`) is triggered on the completion of an action.
|
||||
|
||||
All infinitive events provide [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) functionality. This provides the ability to stop the execution of an action before it starts.
|
||||
|
||||
{% highlight js %}
|
||||
$('#myModal').on('show.bs.modal', function (e) {
|
||||
if (!data) return e.preventDefault() // stops modal from being shown
|
||||
})
|
||||
{% endhighlight %}
|
||||
|
||||
## Version numbers
|
||||
|
||||
The version of each of Bootstrap's jQuery plugins can be accessed via the `VERSION` property of the plugin's constructor. For example, for the tooltip plugin:
|
||||
@@ -100,8 +121,8 @@ Bootstrap's plugins don't fall back particularly gracefully when JavaScript is d
|
||||
**Bootstrap does not officially support third-party JavaScript libraries** like Prototype or jQuery UI. Despite `.noConflict` and namespaced events, there may be compatibility problems that you need to fix on your own.
|
||||
{% endcallout %}
|
||||
|
||||
## Transitions
|
||||
## Util
|
||||
|
||||
For simple transition effects, include `transition.js` once alongside the other JS files. If you're using the compiled (or minified) `bootstrap.js`, there is no need to include this—it's already there.
|
||||
All Bootstrap Javascript depend on `util.js` and it has to be included alongside the other JS files. If you're using the compiled (or minified) `bootstrap.js`, there is no need to include this—it's already there.
|
||||
|
||||
Transition.js is a basic helper for `transitionEnd` events as well as a CSS transition emulator. It's used by the other plugins to check for CSS transition support and to catch hanging transitions.
|
||||
`util.js` includes utility functions and a basic helper for `transitionEnd` events as well as a CSS transition emulator. It's used by the other plugins to check for CSS transition support and to catch hanging transitions.
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Customize Bootstrap with Sass variables, easily toggling global pre
|
||||
group: getting-started
|
||||
---
|
||||
|
||||
Customize Bootstrap 4 with our built-in custom variables file and easily toggle global CSS preferences with new `$enable-*` Sass variables. Override a variable's value and recompile with the included Gruntfile as needed.
|
||||
Customize Bootstrap 4 with our built-in custom variables file and easily toggle global CSS preferences with new `$enable-*` Sass variables. Override a variable's value and recompile with `npm run test` as needed.
|
||||
|
||||
## Customizing variables
|
||||
|
||||
@@ -31,10 +31,11 @@ You can find and customize these variables for key global options in our `_varia
|
||||
|
||||
| Variable | Values | Description |
|
||||
| --------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| `$spacer` | `1rem` (default), or any value > 0 | Specifies the default spacer value for our spacer utilities. |
|
||||
| `$spacer` | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities](/utilities/spacing/). |
|
||||
| `$enable-rounded` | `true` (default) or `false` | Enables predefined `border-radius` styles on various components. |
|
||||
| `$enable-shadows` | `true` or `false` (default) | Enables predefined `box-shadow` styles on various components. |
|
||||
| `$enable-gradients` | `true` or `false` (default) | Enables predefined gradients via `background-image` styles on various components. |
|
||||
| `$enable-transitions` | `true` (default) or `false` | Enables predefined `transition`s on various components. |
|
||||
| `$enable-hover-media-query` | `true` or `false` (default) | ... |
|
||||
| `$enable-grid-classes` | `true` (default) or `false` | Enables the generation of CSS classes for the grid system (e.g., `.container`, `.row`, `.col-md-1`, etc.). |
|
||||
| `$enable-print-styles` | `true` (default) or `false` | Enables styles for optimizing printing. |
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
layout: docs
|
||||
title: Webpack
|
||||
description: Learn how to install Bootstrap using webpack 2
|
||||
group: getting-started
|
||||
---
|
||||
|
||||
Use [webpack v2.x](https://webpack.js.org/) to bundle Bootstrap into your project.
|
||||
|
||||
|
||||
## Contents
|
||||
|
||||
* Will be replaced with the ToC, excluding the "Contents" header
|
||||
{:toc}
|
||||
|
||||
## Installing Bootstrap
|
||||
|
||||
[Install bootstrap](/getting-started/download/#npm) as a node module using npm.
|
||||
|
||||
## Importing JavaScript
|
||||
|
||||
Import [Bootstrap's JavaScript](/getting-started/javascript/) by adding this line to your app's entry point (usally `index.js` or `app.js`):
|
||||
|
||||
{% highlight js %}
|
||||
import 'bootstrap';
|
||||
{% endhighlight %}
|
||||
|
||||
Alternatively, you may **import plugins individually** as needed:
|
||||
|
||||
{% highlight js %}
|
||||
import 'bootstrap/js/dist/util';
|
||||
import 'bootstrap/js/dist/dropdown';
|
||||
...
|
||||
{% endhighlight %}
|
||||
|
||||
Bootstrap is dependent on [jQuery](https://jquery.com/) and [Popper](https://popper.js.org/), so npm will install them for you if needed. But they must be explicitly provided by webpack. Add the following code to the `plugins` section in your webpack config file:
|
||||
|
||||
{% highlight js %}
|
||||
plugins: [
|
||||
...
|
||||
new webpack.ProvidePlugin({
|
||||
$: 'jquery',
|
||||
jQuery: 'jquery',
|
||||
'window.jQuery': 'jquery',
|
||||
Popper: ['popper.js', 'default'],
|
||||
// In case you imported plugins individually, you must also require them here:
|
||||
Util: "exports-loader?Util!bootstrap/js/dist/util",
|
||||
Dropdown: "exports-loader?Dropdown!bootstrap/js/dist/dropdown",
|
||||
...
|
||||
})
|
||||
...
|
||||
]
|
||||
{% endhighlight %}
|
||||
|
||||
{% callout warning %}
|
||||
Notice that if you chose to **import plugins individually**, you must also install [exports-loader](https://github.com/webpack-contrib/exports-loader)
|
||||
{% endcallout %}
|
||||
|
||||
## Importing Styles
|
||||
|
||||
### Importing Precompiled SASS
|
||||
|
||||
To enjoy the full potential of Bootstrap and customize it to your needs, use the source files as a part of your project's bundling process.
|
||||
|
||||
First, create your own `_custom.scss` and use it to override the [built-in custom variables](/getting-started/options/). Then, use your main sass file to import your custom variables, followed by Bootstrap:
|
||||
{% highlight scss %}
|
||||
@import "custom";
|
||||
@import "~bootstrap/scss/bootstrap";
|
||||
{% endhighlight %}
|
||||
|
||||
For Bootstrap to compile, make sure you install and use the required loaders: [sass-loader](https://github.com/webpack-contrib/sass-loader), [postcss-loader](https://github.com/postcss/postcss-loader) with [Autoprefixer](https://github.com/postcss/autoprefixer#webpack) and [postcss-flexbugs-fixes](https://github.com/luisrudge/postcss-flexbugs-fixes). With minimal setup, your webpack config should include this rule or similar:
|
||||
|
||||
{% highlight js %}
|
||||
...
|
||||
{
|
||||
test: /\.(scss)$/,
|
||||
use: [{
|
||||
loader: 'style-loader', // inject CSS to page
|
||||
}, {
|
||||
loader: 'css-loader', // translates CSS into CommonJS modules
|
||||
}, {
|
||||
loader: 'postcss-loader', // Run post css actions
|
||||
options: {
|
||||
plugins: function () { // post css plugins, can be exported to postcss.config.js
|
||||
return [
|
||||
require('precss'),
|
||||
require('autoprefixer')
|
||||
];
|
||||
}
|
||||
}
|
||||
}, {
|
||||
loader: 'sass-loader' // compiles SASS to CSS
|
||||
}]
|
||||
},
|
||||
...
|
||||
{% endhighlight %}
|
||||
|
||||
### Importing Compiled CSS
|
||||
|
||||
Alternatively, you may use Bootstrap's ready-to-use css by simply adding this line to your project's entry point:
|
||||
|
||||
{% highlight js %}
|
||||
import 'bootstrap/dist/css/bootstrap.min.css';
|
||||
{% endhighlight %}
|
||||
|
||||
In this case you may use your existing rule for `css` without any special modifications to webpack config.
|
||||
Reference in New Issue
Block a user