Changing Bootstrap Sass Variables For Joomla Templates
You have two essential options when it comes to adding custom style to Bootstrap. You can either modify a copy of Bootstrap’s source scss files and import them into your template, or create a separate stylesheet and overwrite individual bootstrap classes. In this guide, I’ll be focusing on modifying a copy of Bootstrap, so the variables may be easily edited. This guide’s targeted at beginners.
Cassiopeia, and my example templates joomstarter and Very Simple Template (VST) all use Sass to compile the template stylesheets and Bootstrap’s stylesheets all into one template.min.css file for display on the website. This means in order to change a setting in Bootstrap, we must edit Bootstrap’s scss files and then recompile the entirety of Bootstrap’s scss files and the template’s scss files back into template.min.css using Sass. If you already know how to use Sass, this should be relatively easy. If you’re new to Sass, I’ll tell you where to put the files, what code to edit, and what Sass commands to use.
The guide on creating a simple template has a short section on installing Sass in Windows (under the Getting Started part). So ensure Sass is installed and ready to go on your computer.
Bootstrap contains a file called “_variables.scss” which holds hundreds of different values you can change. These variables define things like the amount of columns you can use, the widths of your viewports, the colors of your buttons, and much more. You’ll likely want to change these settings, so the Bootstrap components match the color scheme of your website.
Determine Bootstrap Source
First off, you need to figure out where your template is getting Bootstrap’s scss stylesheets from. They could come from several places.
With Cassiopeia, the template’s scss file at site_root/media/templates/site/cassiopeia/scss/template.scss imports Bootstrap’s scss files from site_root/media/vendor/bootstrap/scss and then overrides some of the Bootstrap styles using stylesheets in site_root/media/templates/site/cassiopeia/scss/vendor/bootstrap
If you’re using JoomStarter or very simple template, bootstrap comes from site_root/media/templates/site/joomstarter/scss/vendor/bootstrap I included all of bootstrap’s files in the media/vendor folder of the template itself, rather than getting them from the site_root/media/vendor/bootstrap/ folder. This is how I would suggest doing it if you want greater control over Bootstrap.
Finally, your template might load bootstrap’s css separately from the rest of the template css, using a CDN or a direct link to a bootstrap.min.css file somewhere on your server.
Setting Up Bootstrap
I’d encourage you to remove any references to Bootstrap’s css files from your template. If index.php loads bootstrap’s css from a CDN, remove that link. If your template’s scss file loads bootstrap from anywhere other than the template’s direct media folder, remove that import statement. If your joomla.assets.json file loads it from elsewhere, remove that too. If you’re using joomstarter or VST, you’re good to go, and don’t have to make any of the following changes (you may skip to the next section on modifying variables). Keep any references to the template.min.css file.
Bootstrap isn’t just CSS, it’s JavaScript as well. It’s up to you if you want to keep using Joomla’s copy of bootstrap.min.js or install another version. I think it’s probably best practice to use whatever version Joomla is currently using. At the time of writing, Joomla 4/5 loads Bootstrap version 5.x from site_root/media/vendor/bootstrap/js/bootstrap-es5.min.js
You can view the bootstrap version being used by looking at the page source on any page that uses bootstrap.
Go to the Bootstrap download page and download the source files for the version of Bootstrap that matches the version Joomla is using. We want the scss files.
Copy the contents of the entire Bootstrap scss folder into a new folder at site_root/media/templates/site/yourtemplate/scss/vendor/bootstrap
When complete, all the scss files for Bootstrap should be at site_root/media/templates/site/yourtemplate/scss/vendor/bootstrap
Your template’s main scss file should be located at site_root/media/templates/site/yourtemplate/scss/template.scss
Open the template.scss file (or main.scss file, or whatever it’s called for your template).
Remove any lines importing Bootstrap from “../../../../vendor/bootstrap/scss/…” or elsewhere, if they exist.
Replace them with this, or add this to the top of your template.scss file.
@import "vendor/bootstrap/functions";
@import "vendor/bootstrap/variables";
@import "vendor/bootstrap/bootstrap";
Code language: CSS (css)
Save the template.scss file once you’ve added the imports.
Now, when you compile your template, it should compile it using the scss files located in site_root/media/templates/site/yourtemplate/scss/vendor/bootstrap instead of site_root/media/vendor/bootstrap/scss
Open command prompt and navigate to the directory of your template’s scss files.
Example:
cd D:\xampp\htdocs\joomla\media\templates\site\verysimple\scss
Compile your template.scss file and make sure there are no errors. It will alert you if it couldn’t find bootstrap. If it couldn’t, ensure you placed the .scss files in the correct directories and have no typos anywhere.
sass template.scss:..\css\template.min.css --style compressed
If the command completes without an error message, you’ve done it successfully. Now, you can change the settings in the Bootstrap scss files to your liking.
Sample Bootstrap Edits
In this example, I’m going to change some Bootstrap variables I’m using in my very simple template. This will alter the appearance of the template.
I’m starting with a template that looks like this:
The blue color is coming from Bootstrap’s primary color variable. The greyish color behind the read more button is coming from bootstrap’s secondary color. We can easily customize these, and it will change the colors in many different areas of the site that use Bootstrap.
Open the bootstrap variables file at site_root/media/templates/site/yourtemplate/scss/vendor/bootstrap/_variables.scss
Around line 70, there are variables you can edit to change the colors. I’m going to modify my primary color to be purple, and my secondary color to be dark red, for demonstration._variables.scss
// scss-docs-start theme-color-variables
$primary: #811b7c !default;
$secondary: #530000 !default;
$success: $green !default;
$info: $cyan !default;
$warning: $yellow !default;
$danger: $red !default;
$light: $gray-100 !default;
$dark: $gray-900 !default;
Code language: SCSS (scss)
Now I re-compile my template.scss file. When I do this, every instance in Bootstrap that uses the primary color and the secondary color is updated to my new values.
If I reload my website (with caching turned off in developer tools), I can see the changes.
The links and the buttons changed color.
You can use the same method to change any variable in _variables.scss – Just make sure you run the sass command when you’re done making changes. I’d encourage you to make a backup in case there are any issues.
Around line 340 of _variables, there are more useful options you can set to true/false. I’ve made some changes so you can see the result.
$enable-caret: true !default;
$enable-rounded: false !default;
$enable-shadows: true !default;
$enable-gradients: true !default;
$enable-transitions: true !default;
$enable-reduced-motion: true !default;
$enable-smooth-scroll: true !default;
$enable-grid-classes: true !default;
$enable-cssgrid: false !default;
$enable-button-pointers: true !default;
$enable-rfs: true !default;
$enable-validation-icons: true !default;
$enable-negative-margins: false !default;
$enable-deprecation-messages: true !default;
$enable-important-utilities: true !default;
Code language: SCSS (scss)
As you can see, now the buttons have a gradient behind them (enable-gradients true) and the edges of buttons are square instead of rounded (enable-rounded).
You can do a lot to your template by just changing these variables. If you want to learn more, you’ll have to reference the official Bootstrap documentation or just try things out.
Note that if Joomla updates to a new version of Bootstrap, your template will still use the older version for the CSS. There could be a conflict between CSS/JS or page elements if any major updates were made. You should double check that there weren’t any major changes and update your Bootstrap scss files in case there’s anything the new version requires or fixes. 99% of the time you probably won’t have to do much, but there is a chance something could break if the versions are incompatible.
If possible, other than changing the variables, avoid making too many changes to bootstrap’s files. This will make it easier to maintain if you need to update to a new version of Bootstrap. You don’t want to have to go back and update 10 different files every time Joomla moves to a new version of Bootstrap.
The alternative is to just override the bootstrap classes individually after you load the default version of bootstrap into your template. This can create some excessive unused CSS code, but may be more maintainable in the long run. For example, you could import bootstrap from root/media/vendor, then individually override the colors of links and primary button classes, if you wanted to. Ensure any style overrides come after Bootstrap is imported or added to the page. You may use developer tools to determine which style classes need to be overwritten on a page-by-page basis.