Setup

Installation

Install the addon if you have not done so already:

ember install ember-bootstrap

Additional dependencies

Configuration

Using the default blueprint

By default, ember-bootstrap installs Bootstrap 4 and uses the installed preprocessor if there is one. You can use the ember-bootstrap default blueprint to switch the Bootstrap version or preprocessor.

Use a CSS preprocessor

To use a CSS preprocessor like Sass or Less instead of plain CSS (highly recommended!), you can use this command to install and set this up:

ember generate ember-bootstrap --preprocessor=sass // or --preprocessor=less

See the Assets guide for details.

Switch to Bootstrap 3

You can switch to Bootstrap 3 by running this command:

ember generate ember-bootstrap --bootstrap-version=3

As Bootstrap 3 includes Less support, you can enable that as well in your Ember app:

ember generate ember-bootstrap --bootstrap-version=3 --preprocessor=less

About the default blueprint

The default blueprint does the following:

  • Removes any unneeded versions of bootstrap and bootstrap-sass from package.json and bower.json
  • Installs the appropriate version of bootstrap or bootstrap-sass as an npm package
  • Removes unneeded dependencies on ember-cli-less and ember-cli-sass
  • Installs ember-cli-less or ember-cli-sass if appropriate
  • Creates app.less or app.scss if appropriate and it doesn't exist
  • Adds the appropriate "@import" statement to your app.less or app.scss if it's not there already
  • Safely edits your ember-cli-build.js to ensure the proper ember-bootstrap settings for your configuration

All configuration options

Besides the above mentioned configuration options that are handled explicitly using the default blueprint, you can further customize your setup with the following options:

Option Allowed values Default Description
bootstrapVersion 3 / 4 4

Specify the Bootstrap version to use. To make sure you have the right dependencies installed, you should use the default blueprint mentioned above to set this!

See the Bootstrap 4 guide for more details.

importBootstrapTheme true / false false

Include the optional bootstrap-theme.css. Only applicable for Bootstrap 3 and when not using a preprocessor.

See the Assets guide for more details.

importBootstrapCSS true / false true if no preprocessor

Include the default static bootstrap.css. Only applicable when not using a preprocessor.

See the Assets guide for more details.

importBootstrapFont true / false true if Bootstrap 3

Include the Glyphicons font. Only applicable for Bootstrap 3.

See the Assets guide for more details.

insertEmberWormholeElementToDom true / false true

Will automatically insert a div into your index.html, where Bootstrap's modals and tooltips will be rendered to. If you set this to false, you will have to add an <div id="ember-bootstrap-wormhole"></div> element by yourself, e.g. into your application.hbs.

This is especially required if you render your Ember app into a custom application root element, e.g. on an server rendered page, where the default div is not available.

whitelist Array of component names

Component tree shaking: include only the listed components into your build, to reduce your JavaScript bundle size. Components not listed here will not be available. You should use either whitelist or blacklist, not both.

Example:

whitelist: ['bs-button', 'bs-modal', 'bs-form']
blacklist Array of component names

Exclude the listed components from your build, to reduce your JavaScript bundle size. See whitelist.

These options can be set in your ember-cli-build.js file:

//your-bootstrap-app/ember-cli-build.js

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-bootstrap': {
      importBootstrapCSS: false,
      blacklist: ['bs-popover', 'bs-accordion']
    }
  });

  return app.toTree();
};