Introduction

In this tutorial I will show you how to customize Bootstrap and create your own Bootstrap themes using Sass, Gulp and the Bootstrap source code. The result will be a theme that you can apply to new and existing Bootstrap 4 projects to give them a new and fresh look. I've already made some open source themes with this workflow, check out Neon Glow or Vibrant Sea for to see two examples. If you prefer a less code-intense approach, you can also check out this Bootstrap builder which offers a web interface to customize the default Bootstrap theme.

Demonstration

In this video I'll show you how the Theme Kit works. You can watch this for a quick view of the essentials. If you're really in a hurry you can even skip the intro and start at 1:34 for the most juicy part. Farther below you'll find step-by-step instructions to get started.

Step 1: Prerequisites

Short version: You need npm and gulp. A text editor and your command line too.

Long version: In order to customize Bootstrap, we will rebuild Bootstrap 4 from the source code, modifying Sass variables and making use of Bootstrap's mixins and functions. To use the theme kit you'll need at least a text editor and node.js installed on your system. You can get node from nodejs.org. Once installed, you should be able to run the command npm from your command line like so:

alex@ubuntuVM:~$ npm -v 5.5.1

After that, you can install a node package called Gulp, which you can do by typing npm install -g gulp-cli . Finally you should be able to run gulp :

alex@ubuntuVM:~$ gulp -v [16:35:47] CLI version 1.4.0

Note: Your version numbers could be slightly different, but that shouldn't be a problem.

The Bootstrap Theme Kit

Despite its glamorous name and pompous presentation, the theme kit is a humble package. It's a basic project that includes three main parts:

A Sass file structure with the correct imports already in place

A Gulp script that takes care of building, minifying and prefixing the CSS code

An HTML file with Bootstrap components to allow for a quick feedback loop

If you've already got a web project, you would probably want to imitate these techniques with your own build system. The theme kit is simply a minimal project that allows for a quick start and to play around with the theme features without too much effort.

Step 2: Building the theme

After downloading and extracting the Theme Kit, you'll have to run npm install inside the directory to pull all the dependencies. This will download the Bootstrap 4 source code as well as the Sass transpiler for you.

alex@ubuntuVM:~/theme-kit$ npm install ... added 499 packages in 5.839s

Oof, that's a lot of packages. Welcome to npm :-). The packages are stored under node_modules/, so they won't pollute anything outside the project directory. Once the dependencies are installed, you can run gulp to run the build script. You can also run gulp watch to run the Gulp watcher which will run the build each time you change one of the Sass files. This is the most practical thing to do when creating a theme.

alex@ubuntuVM:~/theme-kit$ gulp watch [18:02:30] Using gulpfile ~/theme-kit/gulpfile.js [18:02:30] Starting 'build-theme'... [18:02:32] Finished 'build-theme' after 1.45 s [18:02:32] Starting 'watch'... [18:02:32] Finished 'watch' after 5.39 ms

Step 3: Displaying the theme in the browser

Now that we have the build script running, let's have a look at our theme's current state in the browser. You can open index.html in your browser of choice. Optional: What I usually do here is I run a simple development web server right in the project directory using something like php -S 0.0.0.0:8080 , so I can then navigate to localhost:8080 instead of opening the file from the file explorer. But this is not strictly necessary.

As you can see, there's a collection of relevant components on the screen, organized into a layout that fits a 1920x1080 display. At this point they're built with the default Bootstrap 4 style, but we're about to change that.

Step 4: Modifying the variables

With the gulp watcher running in the background and our testing page loaded in the browser we can now get to theming. Let's have a look at the main Sass file now, which is scss/mytheme.scss:

scss/mytheme.scss

@import 'custom-variables' ; @import '../node_modules/bootstrap/scss/bootstrap' ; @import 'custom-styles' ;

As you can see, this imports our two other Sass files and the Bootstrap source code which is under node_modules/bootstrap/. Our files custom-variables and custom-styles are empty, which is why our theme is essentially just standard Bootstrap 4 right now.

Okay, let's start off with an easy win: Modifying the existing Bootstrap variables. Open node_modules/bootstrap/ scss/_variables.scss to have a look at the options that Bootstrap gives us:

node_modules/bootstrap/ scss/_variables.scss

// this is but a tiny snippet of _variables.scss $primary : $blue ! default ; $secondary : $gray-600 ! default ; $success : $green ! default ; $info : $cyan ! default ; $warning : $yellow ! default ; $danger : $red ! default ; $light : $gray-100 ! default ; $dark : $gray-800 ! default ;

To modify these, we'll make use of the !default rule. Notice how every last variable in this file has !default applied to it. What this means is that the value will only be assigned if it has not yet been defined earlier. So to override these values we simply define them earlier in the Sass code.

This is the opposite of what you would expect when you think about overriding something in CSS. But it's a very powerful mechanic that allows for modifying the colors without injecting any files into Bootstrap's source. The files under node_modules/ remain completely untouched. This is important enough to repeat: Don't change anything in the node_modules/ directory unless you want to lose your work later.

If you take a look at our file scss/mytheme.scss above, you see that the file scss/_custom-variables.scss is included before Bootstrap. So we can use this file to override any of the default variables that Bootstrap uses. Let's add some variables to scss/_custom-variables.scss and see how our theme starts to take a different form:

scss/_custom-variables.scss

// Changing the theme colors $primary : #3ec89d ; $secondary : #3ab7ff ; $success : #65ff9f ; $info : #7164ff ; $warning : #ff9f65 ; $danger : #ff457b ; $light : #f2d4ff ; $dark : #18181d ;

If you save this and refresh your browser, you'll see that all the components have gotten a paint job. At this point I should mention that I'm using a browser plugin for Chrome called LivePage which reloads the page automatically for me on changes. My code editor also has a nifty color picker for CSS colors.

Together with Gulp chugging along in the background, I don't even have to leave my code editor anymore. All of this combined, my workflow looks like this (this video is real time and without sound):