Getting Started with Bootstrap in Drupal 8

By Ivan Zugec / Drupal / May 15, 2019 / 46 Comments

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:

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.

CLICK HERE TO JOIN OUR FREE 3 PART BOOTSTRAP EMAIL COURSE

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:

Table of Contents

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 cssdirectory. 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 THEMENAMEand 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