Guide · Open source

How to use bootstrap-sass: install, configure and override Bootstrap 3 variables

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

bootstrap-sass is an official Sass port of Bootstrap 3, the front-end toolkit for styling websites. It is meant to be added to an existing project, mainly a Ruby on Rails app with the asset pipeline, or installed through npm or Bower. This guide shows how to install it, import it, customize it with Sass variables and check whether it is the right version for your project.

Bootstrap for Sasstwbs/bootstrap-sass · ★ 12.5k · MIT Install options & downloads

Quick start

1Pick your environment. Choose the Rails gem, npm or Bower route based on your project. Confirm you need Bootstrap 3, since bootstrap-sass does not cover Bootstrap 4.
2Install the package. Add the bootstrap-sass gem to your Gemfile and run bundle install, or run npm install bootstrap-sass, or run bower install bootstrap-sass.
3Rename your stylesheet. If your Rails app has application.css, rename it to application.scss so Sass is used, and replace require statements with @import.
4Import Bootstrap. In application.scss, import bootstrap-sprockets first, then bootstrap.
5Add the JavaScript. In application.js, require bootstrap-sprockets, with jQuery loaded first.
6Override variables. Redefine Bootstrap Sass variables before the bootstrap import to customize colours and components.

Check whether bootstrap-sass fits your project

bootstrap-sass covers Bootstrap 3 only. The README states that Bootstrap 4 has its own repositories: use the Bootstrap rubygem if you use Ruby, and the main Bootstrap repo otherwise.

It is a good fit for Rails developers who already use the asset pipeline, Node.js projects that want Bootstrap 3 Sass via npm, teams that customize Bootstrap by overriding Sass variables, and maintainers of existing Bootstrap 3 sites. It is not a fit if you need plain CSS with no build step, because the README describes a Sass-based setup. Rails 3 apps are also not supported; the last version that works with Rails 3.2 is v3.1.1.0.

Ruby on Rails with the asset pipeline (gem route)
Node.js and npm (npm route)
Bower (Bower route)

Install bootstrap-sass in a Rails app

Add the gem to your Gemfile and make sure the sass-rails gem is present. It is added to new Rails applications by default. Then run bundle install and restart your server so the files are available through the pipeline.

Rename application.css to application.scss if your app has one, because a .css file is served instead of Sass. Remove the require_self and require_tree statements and use @import instead. Do not use *= require in Sass files, or other stylesheets cannot access the Bootstrap mixins or variables.

Bootstrap JavaScript depends on jQuery. On Rails 5.1+, add the jquery-rails gem.
Import bootstrap-sprockets before bootstrap in application.scss, otherwise the icon fonts will not work.
Do not include both bootstrap-sprockets and bootstrap in application.js.

gem 'bootstrap-sass', '~> 3.4.1'
gem 'sassc-rails', '>= 2.1.0'

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

Install bootstrap-sass with npm or Bower

For Node.js projects, install the package with npm. The Bower package is compatible with node-sass 3.2.0+, and you can install it with Bower instead. The Bower package's bower.json main field lists the main _bootstrap.scss and the static assets (fonts and JS), which the README says is compatible with asset managers such as wiredep.

When using the Bower package in Rails, the README asks you to add Bower asset paths and a minimum Sass number precision to config/application.rb, then point your imports at bootstrap-sass/assets/stylesheets.

$ npm install bootstrap-sass

$ bower install bootstrap-sass

Import Bootstrap and override Sass variables

Import Bootstrap into a Sass file such as application.scss to get all of its styles, mixins and variables. To use only some components, copy _bootstrap.scss to your assets as _bootstrap-custom.scss, comment out the components you don't need, and import that file instead.

To customize, redefine a Bootstrap variable before the @import line. The full list of variables is in the Bootstrap customize documentation linked from the README.

Optional theme: import bootstrap/theme after bootstrap.
Use precision of at least 8 for Sass numbers; sassc-rails sets this automatically.
Bootstrap requires Autoprefixer. The README gives a browser list matching upstream Bootstrap's compatibility.

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

@import "bootstrap";

Add Bootstrap JavaScript

The file assets/javascripts/bootstrap.js contains all of Bootstrap's JavaScript in the correct order. If you use Sprockets or Mincer, require bootstrap-sprockets to load all modules, or require individual modules such as bootstrap/modal as long as you also require their dependencies. The Bootstrap JS documentation lists those dependencies.

//= require bootstrap-sprockets

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

Troubleshoot common setup issues

Most problems come from file names or import order. If styles do not change, check that your stylesheet has a .scss (or .sass) extension and that no leftover .css file is being served. If icon fonts are missing, check that bootstrap-sprockets is imported before bootstrap. If Sass reports number precision errors, set precision to at least 8 as described in the configuration section.

The version number may differ from upstream Bootstrap in the last (patch) number, because Sass-specific changes are released as patches.

What people use it for

Adding Bootstrap 3 styling to an existing Rails app that uses the asset pipeline
Building a Node.js project that needs Bootstrap 3 Sass installed from npm
Customizing navbar colours by overriding Sass variables before import
Trimming Bootstrap down to the components you use by copying _bootstrap.scss into a custom file

Frequently asked questions

Is bootstrap-sass free to use?

bootstrap-sass is released under the MIT licence, as listed in its project details. The README does not describe any paid tier.

How do I install bootstrap-sass?

In a Rails app, add the bootstrap-sass gem to your Gemfile and run bundle install. In a Node.js project, run npm install bootstrap-sass, or run bower install bootstrap-sass for the Bower package.

Does bootstrap-sass work with Bootstrap 4?

No. The README says bootstrap-sass is Bootstrap 3 only. For Bootstrap 4, use the Bootstrap rubygem if you use Ruby, or the main Bootstrap repo otherwise.

Does bootstrap-sass work with Rails 3?

No. The README says the gem is no longer compatible with Rails 3. The latest version compatible with Rails 3.2 is v3.1.1.0.

Why are my Bootstrap icon fonts missing?

The README says bootstrap-sprockets must be imported before bootstrap for the icon fonts to work. Check the order of your @import lines in application.scss.

What are the alternatives to bootstrap-sass?

The project lists Bootstrap (main repo), bootstrap-rubygem, Bulma and Foundation for Sites as comparable projects. Choose Bootstrap 4 or later through the main repo or rubygem if you are starting a new project.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use bootstrap-sass if you maintain a Bootstrap 3 site, work in a Rails asset pipeline, or want Bootstrap 3 Sass from npm and need to override its variables. Pick the Bootstrap main repo or rubygem for Bootstrap 4, or a different framework such as Bulma or Foundation for Sites if you are starting fresh and do not need Bootstrap 3.

Install options & downloads