bootstrap-sass

Official Sass port of Bootstrap 2 and 3.

Subscribe to updates I use bootstrap-sass


Statistics on bootstrap-sass

Number of watchers on Github 12597
Number of open issues 53
Average time to close an issue 24 days
Main language Ruby
Average time to merge a PR 5 days
Open pull requests 10+
Closed pull requests 58+
Last commit 11 months ago
Repo Created about 7 years ago
Repo Last Updated 6 months ago
Size 3.01 MB
Homepage http://getbootstr...
Organization / Authortwbs
Latest Releasev3.3.6
Contributors98
Page Updated
Do you use bootstrap-sass? Leave a review!
View open issues (53)
View bootstrap-sass activity
View on github
Latest Open Source Launches
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating bootstrap-sass for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Bootstrap for Sass

Gem Version npm version Bower Version Build Status

bootstrap-sass is a Sass-powered version of Bootstrap 3, ready to drop right into your Sass powered applications.

This is Bootstrap 3. For Bootstrap 4 use the Bootstrap Ruby gem if you use Ruby, and the main repo otherwise.

Installation

Please see the appropriate guide for your environment of choice:

a. Ruby on Rails

bootstrap-sass is easy to drop into Rails with the asset pipeline.

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.

gem 'bootstrap-sass', '~> 3.3.7'
gem 'sass-rails', '>= 3.2'

bundle install and restart your server to make the files available through the pipeline.

Import Bootstrap styles in app/assets/stylesheets/application.scss:

// "bootstrap-sprockets" must be imported before "bootstrap" and "bootstrap/variables"
@import "bootstrap-sprockets";
@import "bootstrap";

bootstrap-sprockets must be imported before bootstrap for the icon fonts to work.

Make sure the file has .scss extension (or .sass for Sass syntax). If you have just generated a new Rails app, it may come with a .css file instead. If this file exists, it will be served instead of Sass, so rename it:

$ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss

Then, remove all the *= require_self and *= require_tree . statements from the sass file. Instead, use @import to import Sass files.

Do not use *= require in Sass or your other stylesheets will not be able to access the Bootstrap mixins or variables.

Bootstrap JavaScript depends on jQuery. If you're using Rails 5.1+, add the jquery-rails gem to your Gemfile:

gem 'jquery-rails'
$ bundle install

Require Bootstrap Javascripts in app/assets/javascripts/application.js:

//= require jquery
//= require bootstrap-sprockets

bootstrap-sprockets and bootstrap should not both be included in application.js.

bootstrap-sprockets provides individual Bootstrap Javascript files (alert.js or dropdown.js, for example), while bootstrap provides a concatenated file containing all Bootstrap Javascripts.

Bower with Rails

When using bootstrap-sass Bower package instead of the gem in Rails, configure assets in config/application.rb:

# Bower asset paths
root.join('vendor', 'assets', 'bower_components').to_s.tap do |bower_path|
  config.sass.load_paths << bower_path
  config.assets.paths << bower_path
end
# Precompile Bootstrap fonts
config.assets.precompile << %r(bootstrap-sass/assets/fonts/bootstrap/[\w-]+\.(?:eot|svg|ttf|woff2?)$)
# Minimum Sass number precision required by bootstrap-sass
::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max

Replace Bootstrap @import statements in application.scss with:

$icon-font-path: "bootstrap-sass/assets/fonts/bootstrap/";
@import "bootstrap-sass/assets/stylesheets/bootstrap-sprockets";
@import "bootstrap-sass/assets/stylesheets/bootstrap";

Replace Bootstrap require directive in application.js with:

//= require bootstrap-sass/assets/javascripts/bootstrap-sprockets

Rails 4.x

Please make sure sprockets-rails is at least v2.1.4.

Rails 3.2.x

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.

b. Compass without Rails

Install the gem:

$ gem install bootstrap-sass

If you have an existing Compass project:

  1. Require bootstrap-sass in config.rb:

    require 'bootstrap-sass'
    
  2. Install Bootstrap with:

    $ bundle exec compass install bootstrap -r bootstrap-sass
    

If you are creating a new Compass project, you can generate it with bootstrap-sass support:

$ bundle exec compass create my-new-project -r bootstrap-sass --using bootstrap

or, alternatively, if you're not using a Gemfile for your dependencies:

$ compass create my-new-project -r bootstrap-sass --using bootstrap

This will create a new Compass project with the following files in it:

Some bootstrap-sass mixins may conflict with the Compass ones. If this happens, change the import order so that Compass mixins are loaded later.

c. Bower

bootstrap-sass Bower package is compatible with node-sass 3.2.0+. You can install it with:

$ bower install bootstrap-sass

Sass, JS, and all other assets are located at assets.

By default, bower.json main field list only the main _bootstrap.scss and all the static assets (fonts and JS). This is compatible by default with asset managers such as wiredep.

Node.js Mincer

If you use mincer with node-sass, import Bootstrap like so:

In application.css.ejs.scss (NB .css.ejs.scss):

// Import mincer asset paths helper integration
@import "bootstrap-mincer";
@import "bootstrap";

In application.js:

//= require bootstrap-sprockets

See also this example manifest.js for mincer.

d. npm / Node.js

$ npm install bootstrap-sass

Configuration

Sass

By default all of Bootstrap is imported.

You can also import components explicitly. To start with a full list of modules copy _bootstrap.scss file into your assets as _bootstrap-custom.scss. Then comment out components you do not want from _bootstrap-custom. In the application Sass file, replace @import 'bootstrap' with:

@import 'bootstrap-custom';

Sass: Number Precision

bootstrap-sass requires minimum Sass number precision of 8 (default is 5).

Precision is set for Rails and Compass automatically. When using Ruby Sass compiler standalone or with the Bower version you can set it with:

::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max

Sass: Autoprefixer

Bootstrap requires the use of Autoprefixer. Autoprefixer adds vendor prefixes to CSS rules using values from Can I Use.

To match upstream Bootstrap's level of browser compatibility, set Autoprefixer's browsers option to:

[
  "Android 2.3",
  "Android >= 4",
  "Chrome >= 20",
  "Firefox >= 24",
  "Explorer >= 8",
  "iOS >= 6",
  "Opera >= 12",
  "Safari >= 6"
]

JavaScript

assets/javascripts/bootstrap.js contains all of Bootstrap's JavaScript, concatenated in the correct order.

JavaScript with Sprockets or Mincer

If you use Sprockets or Mincer, you can require bootstrap-sprockets instead to load the individual modules:

// Load all Bootstrap JavaScript
//= require bootstrap-sprockets

You can also load individual modules, provided you also require any dependencies. You can check dependencies in the Bootstrap JS documentation.

//= require bootstrap/scrollspy
//= require bootstrap/modal
//= require bootstrap/dropdown

Fonts

The fonts are referenced as:

"#{$icon-font-path}#{$icon-font-name}.eot"

$icon-font-path defaults to bootstrap/ if asset path helpers are used, and ../fonts/bootstrap/ otherwise.

When using bootstrap-sass with Compass, Sprockets, or Mincer, you must import the relevant path helpers before Bootstrap itself, for example:

@import "bootstrap-compass";
@import "bootstrap";

Usage

Sass

Import Bootstrap into a Sass file (for example, application.scss) to get all of Bootstrap's styles, mixins and variables!

@import "bootstrap";

You can also include optional Bootstrap theme:

@import "bootstrap/theme";

The full list of Bootstrap variables can be found here. You can override these by simply redefining the variable before the @import directive, e.g.:

$navbar-default-bg: #312312;
$light-orange: #ff8c00;
$navbar-default-color: $light-orange;

@import "bootstrap";

Eyeglass

Bootstrap is available as an Eyeglass module. After installing Bootstrap via NPM you can import the Bootstrap library via:

@import "bootstrap-sass/bootstrap"

or import only the parts of Bootstrap you need:

@import "bootstrap-sass/bootstrap/variables";
@import "bootstrap-sass/bootstrap/mixins";
@import "bootstrap-sass/bootstrap/carousel";

Version

Bootstrap for Sass version may differ from the upstream version in the last number, known as PATCH. The patch version may be ahead of the corresponding upstream minor. This happens when we need to release Sass-specific changes.

Before v3.3.2, Bootstrap for Sass version used to reflect the upstream version, with an additional number for Sass-specific changes. This was changed due to Bower and npm compatibility issues.

The upstream versions vs the Bootstrap for Sass versions are:

Upstream Sass
3.3.4+ same
3.3.2 3.3.3
<= 3.3.1 3.3.1.x

Always refer to CHANGELOG.md when upgrading.


Development and Contributing

If you'd like to help with the development of bootstrap-sass itself, read this section.

Upstream Converter

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.

Note: if you're just looking to use Bootstrap 3, see the installation section above.

Upstream changes to the Bootstrap project can now be pulled in using the convert rake task.

Here's an example run that would pull down the master branch from the main twbs/bootstrap repo:

rake convert

This will convert the latest LESS to Sass and update to the latest JS. To convert a specific branch or version, pass the branch name or the commit hash as the first task argument:

rake convert[e8a1df5f060bf7e6631554648e0abde150aedbe4]

The latest converter script is located here and does the following:

  • Converts upstream Bootstrap LESS files to its matching SCSS file.
  • 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.
  • Copies all upstream font files into assets/fonts/bootstrap.
  • Sets Bootstrap::BOOTSTRAP_SHA in version.rb to the branch sha.

This converter fully converts original LESS to SCSS. Conversion is automatic but requires instructions for certain transformations (see converter output). Please submit GitHub issues tagged with conversion.

Credits

bootstrap-sass has a number of major contributors:

and a significant number of other contributors.

You're in good company

bootstrap-sass is used to build some awesome projects all over the web, including Diaspora, rails_admin, Michael Hartl's Rails Tutorial, gitlabhq and kandan.

bootstrap-sass open issues Ask a question     (View All Issues)
  • almost 2 years Update Glyphicon to version 1.9.2
  • almost 2 years Bourbon is not compatible with Bootstrap straight away
  • almost 2 years npm install doesn't work
  • almost 2 years Unnecesary files included in npm package
  • almost 2 years eyeglass import is not consistent with rails/bower/node/etc
  • about 2 years Sass @import "bootstrap-compass" + @import "bootstrap" issue using Compass.
  • about 2 years Compass + Sass not getting all the partials.
  • over 2 years Error when changing 'default' to 'application' in stylesheet tag from application.html.erb file
  • about 3 years glyphicons 404 not loading after removing and copying font files
  • about 3 years Need to specify sprockets version with rails 4.0.1
  • over 3 years Bootstrap not being used after install
  • over 3 years Sourcemaps configuration
bootstrap-sass open pull requests (View All Pulls)
  • Update normalize.css to ver 5.0
  • Update _nav-divider.scss
  • Chore: support `node-sass` version `4.0.0`.
  • Added a tweak for the responsive-visibility mixin for the col tag.
  • Update ejs version because of potential security vulnerability
  • form-control-focus mixin fix
  • Remove extra parens
  • Update README.md
  • Split @font-face declaration into a separate file
  • add refer to add gem for rails 5.1+
bootstrap-sass questions on Stackoverflow (View All Questions)
  • Bootstrap SASS - using mixins in SCSS instead of CSS classes in HTML
  • how to get bootstrap-sass RTL version on Ruby on rails?
  • rails bootstrap-sass font 404 error on staging
  • Unable to load bootstrap with Node-sass, bootstrap-sass
  • Overriding variables of Bootstrap-Sass
  • how to use webpack and bootstrap-sass-loader load bootstrap in rails
  • Install bootstrap-sass on windows 10
  • Jquery issue setting up Bootstrap SASS with gulp
  • 'no such file to load -- bootstrap-sass' using compass and ruby version 2.3 instead of 1.8
  • Bootstrap-SASS Glyphicons Not Rendering With Webpack Build
  • How to deal with fonts in bootstrap-sass and compass? How to include fonts on the page correctly?
  • What's the difference between bower bootstrap-sass and bootstrap-sass-official
  • Error importing outside bootstrap-sass library using webpack
  • Cannot get bootstrap-sass to work with webpack
  • Rails 4 - Styling CSS with Bootstrap Sass
  • Bootstrap-sass is outputting calls to font-path
  • Can't get CSS working on Heroku using Rails 4 with bootstrap-sass gem
  • Why doesn't bootstrap-sass work with Rails?
  • Why do I get an error when I bundle install a bootstrap-sass gem?
  • how to compile bootstrap sass at node.js app
  • How to implement a boostrap template over bootstrap-sass gem
  • Compass, bootstrap-sass and ruby 1.8.7
  • MopaBootstrap - Post-cmd-cmd creates a wrongly bootstrap-sass folder in web
  • Wrapping the bootstrap-sass gem in another gem causes asset manifests to break
  • Using bootstrap-sass, what would be the hidden-xs equivalent to @include make-sm-column( n )
  • I can't modify bootstrap-sass variables in rails application
  • Glyphicons not working with bootstrap-sass in Angular
  • Can't Precompile Assets Rails 4 bootstrap-sass DXImageTransform error
  • import bootstrap-sass to scss file
  • Rails 4, Bootstrap-sass 3: glyphicons not showing in production
bootstrap-sass list of languages used
bootstrap-sass latest release notes
  • Bumps Sass dependency to 3.3.4+ to avoid compatibility issues with @at-root.
  • Bumps node-sass dependency to ~3.4.2 for Node.js v5 compatibility. #986
  • Fixes breadcrumb content issues on libsass. #919
  • Fixes a Rails 5 compatibility issue. #965

Framework version: Bootstrap v3.3.6 See the upstream blog post for style and JavaScript changes.

Fix for standalone Compass extension compatibility. #914

Framework version: Bootstrap v3.3.5

No Sass-specific changes.

Framework version: Bootstrap v3.3.4.

The Ruby gem was originally released as v3.3.4, but has been re-released as v3.3.4.1 due to a file permissions issue. Non-rubygem releases are not affected.

Other projects in Ruby