2 [![Gem Version](https://badge.fury.io/rb/bootstrap-sass.svg)](http://badge.fury.io/rb/bootstrap-sass)
3 [![npm version](https://img.shields.io/npm/v/bootstrap-sass.svg?style=flat)](https://www.npmjs.com/package/bootstrap-sass)
4 [![Bower Version](https://badge.fury.io/bo/bootstrap-sass.svg)](http://badge.fury.io/bo/bootstrap-sass)
5 [![Build Status](https://img.shields.io/travis/twbs/bootstrap-sass.svg)](https://travis-ci.org/twbs/bootstrap-sass)
7 `bootstrap-sass` is a Sass-powered version of [Bootstrap](https://github.com/twbs/bootstrap) 3, ready to drop right into your Sass powered applications.
9 This is Bootstrap 3. For Bootstrap 4 use the [Bootstrap Ruby gem](http://github.com/twbs/bootstrap-rubygem) if you use Ruby, and the [main repo](http://github.com/twbs/bootstrap) otherwise.
13 Please see the appropriate guide for your environment of choice:
15 * [Ruby on Rails](#a-ruby-on-rails).
16 * [Compass](#b-compass-without-rails) not on Rails.
18 * [npm / Node.js](#d-npm--nodejs).
22 `bootstrap-sass` is easy to drop into Rails with the asset pipeline.
24 In your Gemfile you need to add the `bootstrap-sass` gem, and ensure that the `sass-rails` gem is present - it is added to new Rails applications by default.
27 gem 'bootstrap-sass', '~> 3.3.6'
28 gem 'sass-rails', '>= 3.2'
31 `bundle install` and restart your server to make the files available through the pipeline.
33 Import Bootstrap styles in `app/assets/stylesheets/application.scss`:
36 // "bootstrap-sprockets" must be imported before "bootstrap" and "bootstrap/variables"
37 @import "bootstrap-sprockets";
41 `bootstrap-sprockets` must be imported before `bootstrap` for the icon fonts to work.
43 Make sure the file has `.scss` extension (or `.sass` for Sass syntax). If you have just generated a new Rails app,
44 it may come with a `.css` file instead. If this file exists, it will be served instead of Sass, so rename it:
47 $ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss
50 Then, remove all the `*= require_self` and `*= require_tree .` statements from the sass file. Instead, use `@import` to import Sass files.
52 Do not use `*= require` in Sass or your other stylesheets will not be [able to access][antirequire] the Bootstrap mixins or variables.
54 Require Bootstrap Javascripts in `app/assets/javascripts/application.js`:
58 //= require bootstrap-sprockets
61 `bootstrap-sprockets` and `bootstrap` [should not both be included](https://github.com/twbs/bootstrap-sass/issues/829#issuecomment-75153827) in `application.js`.
63 `bootstrap-sprockets` provides individual Bootstrap Javascript files (`alert.js` or `dropdown.js`, for example), while
64 `bootstrap` provides a concatenated file containing all Bootstrap Javascripts.
68 When using [bootstrap-sass Bower package](#c-bower) instead of the gem in Rails, configure assets in `config/application.rb`:
72 root.join('vendor', 'assets', 'bower_components').to_s.tap do |bower_path|
73 config.sass.load_paths << bower_path
74 config.assets.paths << bower_path
76 # Precompile Bootstrap fonts
77 config.assets.precompile << %r(bootstrap-sass/assets/fonts/bootstrap/[\w-]+\.(?:eot|svg|ttf|woff2?)$)
78 # Minimum Sass number precision required by bootstrap-sass
79 ::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max
82 Replace Bootstrap `@import` statements in `application.scss` with:
85 $icon-font-path: "bootstrap-sass/assets/fonts/bootstrap/";
86 @import "bootstrap-sass/assets/stylesheets/bootstrap-sprockets";
87 @import "bootstrap-sass/assets/stylesheets/bootstrap";
90 Replace Bootstrap `require` directive in `application.js` with:
93 //= require bootstrap-sass/assets/javascripts/bootstrap-sprockets
98 Please make sure `sprockets-rails` is at least v2.1.4.
102 bootstrap-sass is no longer compatible with Rails 3. The latest version of bootstrap-sass compatible with Rails 3.2 is v3.1.1.0.
104 ### b. Compass without Rails
109 $ gem install bootstrap-sass
112 If you have an existing Compass project:
114 1. Require `bootstrap-sass` in `config.rb`:
117 require 'bootstrap-sass'
120 2. Install Bootstrap with:
123 $ bundle exec compass install bootstrap -r bootstrap-sass
126 If you are creating a new Compass project, you can generate it with bootstrap-sass support:
129 $ bundle exec compass create my-new-project -r bootstrap-sass --using bootstrap
132 or, alternatively, if you're not using a Gemfile for your dependencies:
135 $ compass create my-new-project -r bootstrap-sass --using bootstrap
138 This will create a new Compass project with the following files in it:
140 * [styles.sass](/templates/project/styles.sass) - main project Sass file, imports Bootstrap and variables.
141 * [_bootstrap-variables.sass](/templates/project/_bootstrap-variables.sass) - all of Bootstrap variables, override them here.
143 Some bootstrap-sass mixins may conflict with the Compass ones.
144 If this happens, change the import order so that Compass mixins are loaded later.
148 bootstrap-sass Bower package is compatible with node-sass 3.2.0+. You can install it with:
151 $ bower install bootstrap-sass
154 Sass, JS, and all other assets are located at [assets](/assets).
156 By default, `bower.json` main field list only the main `_bootstrap.scss` and all the static assets (fonts and JS).
157 This is compatible by default with asset managers such as [wiredep](https://github.com/taptapship/wiredep).
161 If you use [mincer][mincer] with node-sass, import Bootstrap like so:
163 In `application.css.ejs.scss` (NB **.css.ejs.scss**):
166 // Import mincer asset paths helper integration
167 @import "bootstrap-mincer";
174 //= require bootstrap-sprockets
177 See also this [example manifest.js](/test/dummy_node_mincer/manifest.js) for mincer.
181 $ npm install bootstrap-sass
189 By default all of Bootstrap is imported.
191 You can also import components explicitly. To start with a full list of modules copy
192 [`_bootstrap.scss`](assets/stylesheets/_bootstrap.scss) file into your assets as `_bootstrap-custom.scss`.
193 Then comment out components you do not want from `_bootstrap-custom`.
194 In the application Sass file, replace `@import 'bootstrap'` with:
197 @import 'bootstrap-custom';
200 ### Sass: Number Precision
202 bootstrap-sass [requires](https://github.com/twbs/bootstrap-sass/issues/409) minimum [Sass number precision][sass-precision] of 8 (default is 5).
204 Precision is set for Rails and Compass automatically.
205 When using Ruby Sass compiler standalone or with the Bower version you can set it with:
208 ::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max
211 ### Sass: Autoprefixer
213 Bootstrap requires the use of [Autoprefixer][autoprefixer].
214 [Autoprefixer][autoprefixer] adds vendor prefixes to CSS rules using values from [Can I Use](http://caniuse.com/).
216 To match [upstream Bootstrap's level of browser compatibility](http://getbootstrap.com/getting-started/#support), set Autoprefixer's `browsers` option to:
232 [`assets/javascripts/bootstrap.js`](/assets/javascripts/bootstrap.js) contains all of Bootstrap's JavaScript,
233 concatenated in the [correct order](/assets/javascripts/bootstrap-sprockets.js).
236 #### JavaScript with Sprockets or Mincer
238 If you use Sprockets or Mincer, you can require `bootstrap-sprockets` instead to load the individual modules:
241 // Load all Bootstrap JavaScript
242 //= require bootstrap-sprockets
245 You can also load individual modules, provided you also require any dependencies.
246 You can check dependencies in the [Bootstrap JS documentation][jsdocs].
249 //= require bootstrap/scrollspy
250 //= require bootstrap/modal
251 //= require bootstrap/dropdown
256 The fonts are referenced as:
259 "#{$icon-font-path}#{$icon-font-name}.eot"
262 `$icon-font-path` defaults to `bootstrap/` if asset path helpers are used, and `../fonts/bootstrap/` otherwise.
264 When using bootstrap-sass with Compass, Sprockets, or Mincer, you **must** import the relevant path helpers before Bootstrap itself, for example:
267 @import "bootstrap-compass";
275 Import Bootstrap into a Sass file (for example, `application.scss`) to get all of Bootstrap's styles, mixins and variables!
281 You can also include optional Bootstrap theme:
284 @import "bootstrap/theme";
287 The full list of Bootstrap variables can be found [here](http://getbootstrap.com/customize/#less-variables). You can override these by simply redefining the variable before the `@import` directive, e.g.:
290 $navbar-default-bg: #312312;
291 $light-orange: #ff8c00;
292 $navbar-default-color: $light-orange;
299 Bootstrap is available as an [Eyeglass](https://github.com/sass-eyeglass/eyeglass) module. After installing Bootstrap via NPM you can import the Bootstrap library via:
302 @import "bootstrap-sass/bootstrap"
305 or import only the parts of Bootstrap you need:
308 @import "bootstrap-sass/bootstrap/variables";
309 @import "bootstrap-sass/bootstrap/mixins";
310 @import "bootstrap-sass/bootstrap/carousel";
315 Bootstrap for Sass version may differ from the upstream version in the last number, known as
316 [PATCH](http://semver.org/spec/v2.0.0.html). The patch version may be ahead of the corresponding upstream minor.
317 This happens when we need to release Sass-specific changes.
319 Before v3.3.2, Bootstrap for Sass version used to reflect the upstream version, with an additional number for
320 Sass-specific changes. This was changed due to Bower and npm compatibility issues.
322 The upstream versions vs the Bootstrap for Sass versions are:
325 |---------:|--------:|
328 | <= 3.3.1 | 3.3.1.x |
330 Always refer to [CHANGELOG.md](/CHANGELOG.md) when upgrading.
334 ## Development and Contributing
336 If you'd like to help with the development of bootstrap-sass itself, read this section.
338 ### Upstream Converter
340 Keeping bootstrap-sass in sync with upstream changes from Bootstrap used to be an error prone and time consuming manual process. With Bootstrap 3 we have introduced a converter that automates this.
342 **Note: if you're just looking to *use* Bootstrap 3, see the [installation](#installation) section above.**
344 Upstream changes to the Bootstrap project can now be pulled in using the `convert` rake task.
346 Here's an example run that would pull down the master branch from the main [twbs/bootstrap](https://github.com/twbs/bootstrap) repo:
350 This will convert the latest LESS to Sass and update to the latest JS.
351 To convert a specific branch or version, pass the branch name or the commit hash as the first task argument:
353 rake convert[e8a1df5f060bf7e6631554648e0abde150aedbe4]
355 The latest converter script is located [here][converter] and does the following:
357 * Converts upstream Bootstrap LESS files to its matching SCSS file.
358 * Copies all upstream JavaScript into `assets/javascripts/bootstrap`, a Sprockets manifest at `assets/javascripts/bootstrap-sprockets.js`, and a concatenation at `assets/javascripts/bootstrap.js`.
359 * Copies all upstream font files into `assets/fonts/bootstrap`.
360 * Sets `Bootstrap::BOOTSTRAP_SHA` in [version.rb][version] to the branch sha.
362 This converter fully converts original LESS to SCSS. Conversion is automatic but requires instructions for certain transformations (see converter output).
363 Please submit GitHub issues tagged with `conversion`.
367 bootstrap-sass has a number of major contributors:
369 <!-- feel free to make these link wherever you wish -->
370 * [Thomas McDonald](https://twitter.com/thomasmcdonald_)
371 * [Tristan Harward](http://www.trisweb.com)
373 * [Gleb Mazovetskiy](https://github.com/glebm)
375 and a [significant number of other contributors][contrib].
377 ## You're in good company
378 bootstrap-sass is used to build some awesome projects all over the web, including
379 [Diaspora](https://diasporafoundation.org/), [rails_admin](https://github.com/sferik/rails_admin),
380 Michael Hartl's [Rails Tutorial](https://www.railstutorial.org/), [gitlabhq](http://gitlabhq.com/) and
381 [kandan](http://getkandan.com/).
383 [converter]: https://github.com/twbs/bootstrap-sass/blob/master/tasks/converter/less_conversion.rb
384 [version]: https://github.com/twbs/bootstrap-sass/blob/master/lib/bootstrap-sass/version.rb
385 [contrib]: https://github.com/twbs/bootstrap-sass/graphs/contributors
386 [antirequire]: https://github.com/twbs/bootstrap-sass/issues/79#issuecomment-4428595
387 [jsdocs]: http://getbootstrap.com/javascript/#transitions
388 [sass-precision]: http://sass-lang.com/documentation/Sass/Script/Value/Number.html#precision%3D-class_method
389 [mincer]: https://github.com/nodeca/mincer
390 [autoprefixer]: https://github.com/postcss/autoprefixer