Over the last years, I have seen countless SharePoint projects using Bootstrap. And, unfortunately, some of them had a bad thing in common: a really bad integration with Bootstrap. In this post, I will show you a safe (and extremely simple!) option to use Bootstrap with SharePoint without messing up the “out-of-the-box” SharePoint UI on the classic experience.
The problem – custom master pages…
Don’t take me wrong, Bootstrap is a fantastic framework! Its numbers speak for themselves…
SharePoint developers loved to customize master pages…It was so easy to achieve the final result by having full control over SharePoint pages! And a common customization that people used to do to a SharePoint master page was to add a reference to external libraries. Why? Because it was an extremely simple way to get those frameworks to load on every page, so you could just get that initial task completed and worry about the business case.
The problem is, when you do that, those frameworks really load on every page using that master page, including SharePoint standard pages, and are likely to cause lots of issues as some of those frameworks were built to take over the whole page experience. Using Bootstrap as an example, the framework applies CSS styles to basic HTML elements, completely ruining default SharePoint pages (classic experience).
The solution – SASS!
This solution is using SASS, but it should also work exactly the same way with LESS.
To solve this problem you need to ensure that, instead of loading the external library to the global page scope, you only load it to a defined scope under your control so all the styles will be restricted to that scope.
Ensure you have support for NPM packages and SASS in your project
You can find plenty of information online to help you with this if you need it. I will skip it to keep this post shorter.
Install Bootstrap
Start by installing bootstrap-sass NPM module. This will give you a SASS version of the Bootstrap library
Identify the correct scope
The next thing you need to do is to identify the page scope where Bootstrap will be loaded and available for consumption.
For this example, let’s assume we had a custom div element added to the pages where we wanted to load Bootstrap. Note the custom-page class as we will use it to define our scope.
<div class="custom-page">
...[page elements using Bootstrap go here]...
</div>
Load Bootstrap inside the defined scope
The simplicity of SASS is what makes it amazing. Start by adding a SASS file to your project (or use an existing one if you are already using SASS) and add an entry for your defined scope (selector)
.custom-page {
}
As expected, any CSS properties and rules that you add to that selector will only apply to that scope. Do you already get the point? To limit Bootstrap to the defined scope, we only need to load the library inside the .custom-page selector, and because we have installed bootstrap-sass as a module to our project, we can simply import it from the node_modules folder:
.custom-page {
@import"../../node_modules/bootstrap-sass/assets/stylesheets/bootstrap";
}
Simple, right? Now make sure that the CSS file generated is loaded on your SharePoint pages and you should see the Bootstrap styles applied to your custom elements, but not the “out-of-the-box” SharePoint UI.
Tips
If you do not need the whole Bootstrap library to be loaded, you can instead specify which parts you want to import. To see all the individual elements available simply open the node_modules\bootstrap-sass\assets\stylesheets\bootstrap folder. As an example, if you only wanted to import the bootstrap grid system, you could simply specify it
.custom-page {
@import "../../node_modules/bootstrap-sass/assets/stylesheets/bootstrap/grid";
}
Limitations
Global scope
As you may eventually find out, some Bootstrap components only work if loaded to the global scope. An example of this is the modal dialogs as they rely on a CSS class added to the body HTML tag to apply the styles. In this case, you could simply import Modals to your global page scope (for example right after the limited scope):
// custom page scope
.custom-page {
@import"../../node_modules/bootstrap-sass/assets/stylesheets/bootstrap";
}
// Core variables and mixins
@import "../../node_modules/bootstrap-sass/assets/stylesheets/bootstrap/variables";
@import "../../node_modules/bootstrap-sass/assets/stylesheets/bootstrap/mixins";
// Modals
@import "../../node_modules/bootstrap-sass/assets/stylesheets/bootstrap/modals";
JavaScript
Another thing to keep in mind is that some components use JavaScript to work properly. In this post I have only focused on CSS, but you can also find the source files for the required JavaScript within the bootstrap-sass module under the node_modules\bootstrap-sass\assets\javascripts folder. Hope you find this post useful!