Getting Started with Bootstrap in Drupal 8

This tutorial focuses on Bootstrap 3 and it’s been updated for 8.x-3.19 which comes with a new starter kit. You’ll need Bootstrap 8.x-3.19 and above to follow this tutorial.

Looking for a Bootstrap 4 theme for Drupal 8, then look at:

  1. Radix (Advanced theme which allows you to compile Bootstrap 4 locally)
  2. Barrio (Pulls in Bootstrap via a CDN)

Update May 2019: This tutorial has been updated for Bootstrap 8.x-3.19 which comes with a new starter kit. You’ll need 8.x-3.19 and above to follow this tutorial.

Bootstrap is a front-end framework for building websites. It ships prebuilt CSS and JavaScript components that make building sites fast. It comes with all sorts of common components that every website needs such as a grid system, buttons, drop-down, responsive form elements, carousel (of course) and so much more. As a developer, I don’t want to spend time styling yet another button. I just want to know which CSS class to add to an <a> tag so it looks like a button and I’m good to go.

One complaint about Bootstrap is you can spot it a mile away because a lot of developers use the default look-and-feel. When you see the famous Jumbotron you know it’s a Bootstrap site. But with a little bit of effort, you can make your site look unique.

Now, another good reason to use Bootstrap is when you’re working with an agency who will design the site but has no Drupal expertize. If they can supply HTML wireframes using Bootstrap then it’s much easier to implement them into Drupal. Yes, in the perfect world it’ll be great to receive a fully built Drupal theme which can be enabled and that’s it. But in reality, most design agencies, unless they specialize in Drupal, don’t know it and this is where Bootstrap can help.

By using Bootstrap, it’ll be easier to work with designers and design agencies because you can discuss things using Bootstrap terminology. For example, a designer may ask, “can we have a sidebar on the right which is 3 columns wide”? Or, they may ask, “make this button on the blog listing page small”.

If you have experience using Bootstrap you should know what I mentioned above.

Luckily for us building a Drupal site using Bootstrap is easy thanks to the Bootstrap theme.

In this tutorial, you learn the following:

  1. Bootstrap theme configuration
  2. Create a Bootstrap sub-theme
  3. Compile Bootstrap locally using Sass

What About Bootstrap 4?

The Bootstrap theme as of this writing only supports Bootstrap 3. For details look at #2554199 in the issue queue.

Other Bootstrap Based Themes

Another theme you should evaluate is the Radix theme. If you know of any other Bootstrap based themes please leave a comment.

Getting Started

Before we can begin, go download the Bootstrap theme from drupal.org.

If you use Composer, run the following:

$ composer require drupal/bootstrap

Configuring Bootstrap Theme

Before we jump into the advanced topic of sub-theming or compiling Sass. Let’s first look at what the theme offers out-of-the-box. In this section, we’ll look at some of the theme options.

The level of configuration in a Drupal theme varies a lot, however, the Bootstrap theme has a healthy amount of options. Enough to give you flexibility but not too much that you’re overwhelmed or confused.

Once you’ve downloaded the theme go to Appearance and click on “Install and set as default” on the Bootstrap theme.

Once installed click on “Settings”.

Bootstrap Settings

From the “Override Global Settings” you can configure common Drupal options such as the logo or favicon. If you’ve configured a Drupal theme in the past this should look familiar.

The vertical tabs under “Bootstrap Settings” is where you can configure specific Bootstrap options, let’s look at a few.

Fluid container

The “Fluid container” option,  which can be accessed by going to General then Container, this option adds the container-fluid class which’ll display the main region at full width. By default, the main region has a width of 1200px.

For more details check out the Containers section.

Images

While still under General, click on the Images field-set. This option let’s you configure how images will be handled.

Leave “Responsive Images” checked. This adds an img-responsive class to images making them responsive. It adds a max-width:100% so images are resized when viewed on mobile.

The “Default image shape” drop-down allows you to choose a different style for images which is done via CSS. I always leave this set to “None”.

For more details check out the Images section.

CDN

Let’s now jump down to the “CDN” section.

In this section, you can configure if Bootstrap will be served from a CDN and which version you want to use.

Theme

From the “Theme” drop-down you can choose a different theme. Most of the options come from Bootswatch.

So your Bootstrap site could go from this:

To this:

Tip: After I selected a theme I had to rebuild the site cache. Go to Configuration, Performance and click on “Clear all caches”. By the way, I chose Slate if you’re wondering.

Loading Bootstrap via a CDN is quick to set up, but hard to customize. If you’re planning to use a CSS processor such as Sass or Less then you’ll need to store Bootstrap locally and compile it.

We didn’t cover every option under “Bootstrap settings”, just the main ones. The rest you can figure out on your own.

Create Bootstrap Sub-theme

So far we’ve looked at changing options within the theme which is great for testing, but if you’re going to use Bootstrap on a proper project then it’s recommended you create a sub-theme.

Why Sub-theme?

When you create a sub-theme, the Bootstrap theme will be the “base theme” which means your sub-theme will automatically inherit all templates and assets such as the CSS and JavaScript.

Your sub-theme will automatically use any template from the base theme unless it’s overridden. If you want to modify the page.html.twig then simply copy it from Bootstrap into your sub-theme templates directory and customize. Drupal will automatically pick up the page.html.twig in your sub-theme instead of the one in Bootstrap.

You should never modify the Bootstrap theme. This way you can keep the Bootstrap theme up-to-date.

If you want to learn more about sub-themes in general. Check out the Creating a Drupal 8 sub-theme, or sub-theme of sub-theme documentation page.

Bootstrap Sass Sub-themes

The way you create a sub-theme can vary. Some themes offer a Drush command to create a sub-theme while others offer starter kits which you just copy and change a few file names.

Bootstrap comes with a single starter kit sub-theme which can be configured to pull in the library via a CDN or compile it locally using Sass or Less. The sub-theme is located in the starterkits folder in the theme.

NOTE: Older versions of the Bootstrap theme (8.x-3.18 and below) had a separate starter kit theme for CDN, Sass and Less. With the latest version of Bootstrap (8.x-3.19), now there’s a single starter kit sub-theme.

 

Step 1: Create Sub-theme

Let’s now create a sub-theme and we’ll use Sass to compile Bootstrap, we won’t use a CDN. Why Sass? Well that’s my CSS pre-processor of choice.

If you want to just create a CDN sub-theme, click here.

1. Go into the Bootstrap theme and copy the THEMENAME folder from starterkits and then paste the folder into /themes/custom.

2. Rename the folder from THEMENAME to bootstrap_sass (you can rename it to whatever you want). Once copied and renamed, the path to the sub-theme should be /themes/custom/bootstrap_sass.

Are you required to add sub-themes into a custom folder? No, it’s just best practice when it comes to managing sub-themes.

Your themes folder should look something like this:

3. In the bootstrap_sass sub-theme, replace all instances of THEMENAME in the file name to bootstrap_sass.

Look for the following files:

  • THEMENAME.libraries.yml   => bootstrap_sass.libraries.yml
  • THEMENAME.starterkit.yml => bootstrap_sass.info.yml (NOTE: make sure you change starterkit to info)
  • THEMENAME.theme            => bootstrap_sass.theme
  • /config/install/THEMENAME.settings.yml => bootstrap_sass.settings.yml
  • /config/schema/THEMENAME.schema.yml => bootstrap_sass.schema.yml

4. Now we need to open up a few files and perform a find and replace on the string THEMENAME.

Open the following files:

  • bootstrap_sass.info.yml: Give your sub-theme a name such as “Bootstrap Sass” and find all THEMENAME and replace them with bootstrap_sass.
  • /config/schema/bootstrap_sass.schema.yml: Find all instances of THEMENAME and replace with bootstrap_sass.
  • /config/install/bootstrap_sass.settings.yml: Uncomment cdn_provider and make sure it’s an empty string. This will stop the sub-theme from using the Bootstrap CDN.
  • bootstrap_sass.libraries.yml: Open the libraries file and uncomment the JS section for SASS.

Step 2: Download Bootstrap

In the above section, we just copied a folder and did a find and replace in the THEMENAME string. Now we need to download the actual Bootstrap library and compile the Sass.

1. Go to the Bootstrap Getting Started page and download the Sass version.

2. Extract the downloaded file into bootstrap_sass, once extracted the path should be bootstrap_sass/bootstrap. You may have to rename the folder after it’s extracted.

Step 3: Download Drupal Bootstrap Styles from Github

We need to download an extra bit of Sass styling which integrates Drupal and Bootstrap. All this customization is in the drupal-bootstrap-styles git repo. We do not need all the files in the repository, what we are just after the scss folder in the src/3.x.x/8.x-3.x.

First, download the files in the repository by clicking on “Clone or download” then “Download ZIP”.

 

Go to src/3.x.x/8.x-3.x in drupal-bootstrap-styles and copy the scss folder into bootstrap_sass.

One of the benefits of compiling Bootstrap is the ability to change colors, heading sizes or even the width of the grid. This can all be done by changing the Sass variables located in bootstrap/assets/stylesheets/bootstrap/_variables.scss. Now you shouldn’t change the variables directly in _variables.scss, instead copy the variables you want to change into scss/_default-variables.scss. The next time you compile Bootstrap those variables in _default-variables.scss will override the ones in the library.

It’s recommended that you only copy over the variables needed. Do not copy the whole _variables.scss file into _default-variables.scss as this will make it harder to debug styling issues.

Step 4: Compile Sass using Laravel Mix

The final piece to complete this sub-theme is to compile Sass. I won’t go into details on how to install and configure Sass, that’ll be a whole tutorial or two on it’s own. Instead, I’ll show you one of many ways to compile Sass. We’ll use Laravel Mix which is a wrapper on top of webpack. Before you begin make sure you download and install Node.js.

1. Go into the sub-theme directory and create a package.json, you can do this by running the following command:

$ npm init -y

Just follow the prompts. Once complete you should see /themes/custom/bootstrap_sass/package.json.

2. Then install Laravel Mix with the following command:

$ npm install laravel-mix --save-dev

Also, download the cross-env package which is required for the scripts to run Laravel Mix.

$ npm install cross-env --save-dev

3. In the sub-theme create another file called webpack.mix.js and add the following to it:

let mix = require('laravel-mix');

mix.sass('scss/style.scss', 'css/');
mix.options({
  processCssUrls: false
});

The code above is pretty straightforward, it’ll tell Laravel Mix to compile scss/styles.scss into the css directory. Once compiled there will be a single file styles.css and the path will be css/styles.css.

4. Open up package.json and replace the scripts section with the one below:

  "scripts": {
    "dev": "npm run development",
    "development": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
    "watch": "npm run development -- --watch",
    "hot": "cross-env NODE_ENV=development node_modules/webpack-dev-server/bin/webpack-dev-server.js --inline --hot --config=node_modules/laravel-mix/setup/webpack.config.js",
    "prod": "npm run production",
    "production": "cross-env NODE_ENV=production node_modules/webpack/bin/webpack.js --no-progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js"
  },

This adds NPM scripts which you’ll need to use to compile the Sass. You’ll need to run these commands from within the sub-theme.

The two important scripts are:

$ npm run watch

Use this script to automatically compile when a file is changed. This should be used locally while developing a site.

$ npm run production

This script should be run when you’re ready to deploy to production. It’ll uglify the CSS and JavaScript file to reduce the size.

Blocks Placements after Installing Sub-theme

When you enable your sub-theme your site could look weird or broken. It could look something like this:

Don’t worry, nothing is wrong you just need to add the blocks into the right regions.

Go to Structure, “Block layout” and rearrange the blocks into the following regions:

Navigation:

  • Site branding

Navigation (Collapsible):

  • Main navigation
  • User account menu

Top Bar:

  • Breadcrumb
  • Status messages
  • Page title
  • Tabs
  • Primary admin actions

Help:

  • Help

Content:

  • Main page content

Secondary:

  • Search
  • Tools

Footer:

  • Powered by Drupal
  • Footer menu

Create CDN Bootstrap Sub-theme

In the section above we focused on creating a Sass sub-theme. Here are the quick steps on how to create a CDN sub-theme, this type is simpler to create than a Sass one.

1. Make a copy of THEMENAME located in starkerkits in the Bootstrap theme into the themes directory. I’ll name the sub-theme bootstrap_cdn.

2. In the bootstrap_cdn sub-theme, replace all instances of THEMENAME in the file name to bootstrap_cdn.

Look for the following files:

  • THEMENAME.libraries.yml   => bootstrap_cdn.libraries.yml
  • THEMENAME.starterkit.yml => bootstrap_cdn.info.yml (NOTE: make sure you change starterkit to info)
  • THEMENAME.theme            => bootstrap_cdn.theme
  • /config/install/THEMENAME.settings.yml => bootstrap_cdn.settings.yml
  • /config/schema/THEMENAME.schema.yml => bootstrap_cdn.schema.yml

4. Now we need to open up a few files and perform a find and replace on the string THEMENAME.

Open the following files:

  • bootstrap_cdn.info.yml: Give your sub-theme a name such as “Bootstrap Sass” and find all THEMENAME and replace them with bootstrap_cdn.
  • /config/schema/bootstrap_cdn.schema.yml: Find all instances of THEMENAME and replace with bootstrap_cdn.

Summary

I hope now you have a better understanding of how to use Bootstrap in your next Drupal project. From a developer’s perspective, it’s great because you can focus on building the site without dealing with small design issues such as styling a button. The Bootstrap theme has a good mix of configuration and flexibility. You can use the theme to quickly spin up a website, however, it’ll look very Bootstrappy. Or you can still use it if you want to fully customize the look-and-feel by compiling it yourself.

Other Bootstrap Modules for Drupal 8

There’s a whole bunch of modules which help you use Bootstrap in other parts of Drupal. There’s a page on drupal.org called Bootstrap related modules which lists them out. The two modules I always use with Bootstrap in Drupal 8 is Bootstrap Layouts and Bootstrap Paragraphs.

Bootstrap Layouts lets you configure a layout using its grid system in Panels and Display Suite. Bootstrap Paragraphs ships a bunch of pre-built paragraph types for Bootstrap.

FAQs

Q: I created a sub-theme but I can’t see it on the Appearance page?

Make sure you change THEMENAME.starterkit.yml to bootstrap_sass.info.yml, replace starterkit with info.

Q: I enabled my sub-theme but the site looks broken.

This can happen when you enable a sub-theme before the parent. The simple workaround is to uninstall your sub-theme and then install the Bootstrap theme first, then install the sub-theme.

Q: None of the JavaScript files are getting loaded?

First, make sure you renamed THEMENAME.libraries.yml to bootstrap_sass.libraries.yml. Then in bootstrap_sass.info.yml make sure you update the libraries sections.

From this:

libraries-extend:
  bootstrap/framework:
    - THEMENAME/framework

To this:

libraries-extend:
  bootstrap/framework:
    - bootstrap_sass/framework

Also, make sure you uncomment the right JS section in the THEMENAME.libraries.yml depending on how you’re compiling Bootstrap. It needs to look like the following for Sass:

framework:
  css:
    theme:
      css/style.css: {}
  js:
    bootstrap/assets/javascripts/bootstrap/affix.js: {}
    bootstrap/assets/javascripts/bootstrap/alert.js: {}
    bootstrap/assets/javascripts/bootstrap/button.js: {}
    bootstrap/assets/javascripts/bootstrap/carousel.js: {}
    bootstrap/assets/javascripts/bootstrap/collapse.js: {}
    bootstrap/assets/javascripts/bootstrap/dropdown.js: {}
    bootstrap/assets/javascripts/bootstrap/modal.js: {}
    bootstrap/assets/javascripts/bootstrap/tooltip.js: {}
    bootstrap/assets/javascripts/bootstrap/popover.js: {}
    bootstrap/assets/javascripts/bootstrap/scrollspy.js: {}
    bootstrap/assets/javascripts/bootstrap/tab.js: {}
    bootstrap/assets/javascripts/bootstrap/transition.js: {}
Ivan Zugec

About Ivan Zugec

Ivan is the founder of Web Wash and spends most of his time consulting and writing about Drupal. He's been working with Drupal for 10 years and has successfully completed several large Drupal projects in Australia.

36 thoughts on “Getting Started with Bootstrap in Drupal 8”

  1. if you receive “Module build failed: Error: ENOENT: no such file or directory…” error
    just run:
    nodejs node_modules/node-sass/scripts/install.js
    npm rebuild node-sass

  2. Hi Ivan,

    First of all great page, great tutorials, thanks in advance for your great work!

    One thing that concerns me in themes for Drupal in general is I could not find any way to add to a theme information what blocks should be applied to what regions. This is confusing because many times i need to figure it out by myself to properly reproduce theme design. I know you mentioned in FAQs load parent first but many themes has it’s owns regions and default blocks aren’t fit and i couldn’t find any recipe attached to themes how this should be configured. I know that styling is tend to be independent from regions but many times in the end theme ended up missing some important sections like for an instance menu. Is there any pattern or design principle that i should stick to?

    I wish that at the moment there’s no well tested BT4 theme, Barrio theme seems to be most proper for this case.

    Thanks

    1. Hi Mateusz,

      I totally agree, knowing which region a block belongs to is difficult.

      The placement of the blocks is stored in configuration YAML files. Most themes ship them in the config/install folder. So the best place to look for them is in there.

      Cheers,
      Ivan

  3. These node commands don’t work in windows. To make it work, need to install “cross-env” node package and change command like below one.

    “watch”: “cross-env NODE_ENV=development node node_modules/webpack/bin/webpack.js –watch –progress –hide-modules –config=node_modules/laravel-mix/setup/webpack.config.js”,

    1. Sorry for double posting. On my Ubuntu, I just have to add –watch-poll to the watch script, so it becomes:

      “watch”: “NODE_ENV=development node_modules/webpack/bin/webpack.js –watch –watch-poll –progress –hide-modules –config=node_modules/laravel-mix/setup/webpack.config.js”,

  4. Hi, I am stuck on Step 2: Download Bootstrap 1.
    I used CDN to name my theme knowing Bootstrap CDN is available on the Download page.
    Is there another way to complete the steps with CDN or do we all need to use SASS?
    Thanks.

  5. Hello, Im quite new to all this and produced all my Bootstrap themes using the CDN, as that was how I learned, 12 months ago when I started, using SASS would have blown my mind, but managed to follow your tutorial (ive never seen let alone used Laravel before) thank you

  6. Thanks for the article. Drupal theming (especially Drupal 8) is very confusing.
    I managed to follow your guide to setup a SASS subtheme, but still see two references to CDN in my page source.
    A stylesheet at cdn.jsdelivr.net/bootswatch/3.3.7/cerulean/bootstrap.min.css
    And a script at cdn.jsdelivr.net/bootstrap/3.3.7/js/bootstrap.min.js
    I can’t seem to find these urls anywhere in the subtheme folder. Did I miss something? I assumed everything would be loaded locally.
    I’m Using Drupal 8 & Bootstrap module 8.x-3.13
    Appearance / Settings / Bootstrap / Advanced / CDN Provider is set to “None”
    Thanks again.

    1. Hi Ehmar,

      If you can’t find the references in the sub-theme, check in the base theme, i.e., Bootstrap.

      Are you using the Bootstrap library module?

      Did you use the sass starterkit when you created the sub-theme?

      Cheers,
      Ivan

      1. That was odd.

        The base theme was still set to CDN Deliver (which seems “correct”). Changing that to “None” also broke the subtheme (that must be where CDN was coming from). I changed the base theme back to CDN (subtheme still set to “None”), cleared the Drupal cache a few times in the process, and now it seems to be working properly.

        Thanks for the extra tips where to look. I copied the sass starter kit from the base theme, and downloaded the sass library from getbootstrap.com (like your article). I didn’t have to touch any of that, just toggle the base CDN and clear the Drupal Cache (though I’m sure I’ve cleared the cache several times after creating the subtheme).

        Thanks again,

  7. Great Information, Ivan. I watched the YouTube version and ran into a problem, so double checked my work here. I think I have everything right. I am running using vagrant, virtualbox, ubuntu on a windows 10 machine. Any insight on the following?

    Below is the error message that I get when running the command ‘npm run dev’.

    C:\Users\Dev\virtualmachines\Drupal8\drupal\web\themes\custom\bootstrap_sass
    λ npm run dev
    npm ERR! file C:\Users\Dev\virtualmachines\Drupal8\drupal\web\themes\custom\bootstrap_sass\package.json
    npm ERR! code EJSONPARSE
    npm ERR! JSON.parse Failed to parse json
    npm ERR! JSON.parse Unexpected string in JSON at position 919 while parsing ‘{
    npm ERR! JSON.parse “name”: “bootstrap_sass”,
    npm ERR! JSON.parse “version’
    npm ERR! JSON.parse Failed to parse package.json data.
    npm ERR! JSON.parse package.json must be actual JSON, not just JavaScript.

    npm ERR! A complete log of this run can be found in:
    npm ERR! C:\Users\Main\AppData\Roaming\npm-cache\_logs\2018-12-01T17_29_37_104Z-debug.log+

  8. Update to my last post…
    1. used JSON Parser to cleanup the ‘package.json’ errors
    2. followed the advice of Logan in his comment on May 22, 2018 at 4:04 pm:
    …at the command prompt entered ‘pm install -g cross-env’
    …added ‘cross-env’ to the Dev Script in package.json

    1. correction…at the command prompt entered ‘npm install -g cross-env’ (I dropped the leading letter ‘n’, when copying earlier.

      1. Hi Ivan,

        Thanks for your reply.

        On my Drupal lightning (8.6.x), I added radix and a radix sub theme based on (themes/contrib/radix/src/kits/default). And added bootswatch on my radix subtheme (see below). It works fine.

        Note: D8 lightning comes with Drush 9 and radix sub-theme cannot be created with drush.
        So, you have to manually create a sub-theme (copying – themes/contrib/radix/src/kits/default).

        on subtheme.style.scss:
        ——————————–
        @import “~bootstrap/scss/functions”;
        //@import “base/variables”;
        @import “~bootswatch/dist/journal/variables”;
        @import “~bootstrap/scss/bootstrap”;
        //@import “subtheme.bootstrap”;
        @import “~bootswatch/dist/journal/bootswatch”;

        Hope this helps to someone.

        Srini

  9. Hans Nieuwenhuis

    Hi,
    I used this tutorial several times on my sites with succes.
    But now I get an error on installing laravel mix
    npm install laravel-mix

    npm ERR! Maximum call stack size exceeded

    Any ideas what causes this ?

  10. Hans Nieuwenhuis

    Hi, found the cause:
    The latest npm install laravel-mix requires that a git client is installed.
    I am on alpine ( docker ) so
    Apk add git
    Solved the problem.
    Regards

  11. when i run npm run dev i am getting this message and its frezzing on command line do you have any idea what am i doing wrong

    Additional dependencies must be installed. This will only take a moment.

    Running: npm install [email protected]* sass –save-dev –production=false

Leave a Comment

You have to agree to the comment policy.

This site uses Akismet to reduce spam. Learn how your comment data is processed.