How to use sass to properly avoid embedding twitter bootstrap class names on HTML

By | December 14, 2017

I am working on a Rails project that is just starting. We want to use twitter bootstrap as a base for our styles, at the beginning we would simply use bootstrap’s class names directly on the HTML code, just like is shown in bootstrap’s documentation, but after reading the following posts:

Lessons learned in maintainable css

Please stop embedding Bootstrap classes in your HTML

it became clear why that’s not the proper why to use bootstrap, so after some more readings:

Decouple Your CSS From HTML


among other, it seemed that using sass @extend was the proper way to avoid using bootstrap’s class names, so instead of doing this:

<button type="submit" class="btn">Search</button>

we would do this:

<button type="submit" class="button">Search</button>

and our sass code would look like this:

.button {
   @extend ".btn";

The problem with that approach, besides the bunch of extra selectors that will be added each time we extend a bootstrap class just to use a different name, is that in cases where bootstrap uses selectors like this:

.form-search .input-append .btn, .form-search .form-input-append .btn {
  border-radius: 0 14px 14px 0;

the button won’t get the right style because sass will not apply that same rule to our custom class name, I mean, sass is not doing this:

.form-search .input-append .btn, .form-search .input-append .button, 
.form-search .form-input-append .btn, .form-search .form-input-append .button {
  border-radius: 0 14px 14px 0;

So I wonder, is this the right way to avoid embedding bootstrap’s class names into HTML, if so, how should I handle this problem (it happens frequently)? if not, what would be a better way to use custom class names but still get the styles from bootstrap.

I really appreciate your thoughts on this. Please keep in mind that I am just learning about overall web design (css, sass, less, html, js, etc.).


When you rename .btn to .button, you also should rename .form-search to .form-searchnew etc?
In that case your sass code in the example above should be something like:

.form-searchnew .input-appendnew .button {
  extend(.form-search .input-append .btn);

Which make sense (i don’t know sass) and results in the css you expect.

I think bootstrap is not about css only. Bootstrap is about css, html(structure) and javascript. Even when you separate css from html i would not easy to migrate to an other framework. Beside the css you will have to change the html structure and javascript call too.

Example migrate from Twitter’s Bootstrap 2 to 3 (see: Updating Bootstrap to version 3 – what do I have to do?). I also wondered if you could migrate by extending the old classes to the new css (see: After reading the migration guide, i think you couldn’t.

Other solutions. Angular JS decouples Twitter’s Bootstrap from javascript. Also in this case migrations does not seem to be painless see: Angular Dialog directives with Bootstrap 3

Maybe also read this post: It refers to Bourdon and Neat.

Example from their website:

<!-- HTML markup for the section right below this code block -->
  <aside>What is it about?</aside>
  <article>Neat is an open source semantic grid framework built on top of Sass and Bourbon…</article>

// Enter Neat
section {
  @include outer-container;
  aside { @include span-columns(3); }
  article { @include span-columns(9); }
// And the result is...

As they say: “it relies entirely on Sass mixins and does not pollute your HTML” which seems the way you’re looking for.


I recommend you have a look at sass placeholder classes in order not to bloath your css. Most likely you won’t be using every single element included in bootstrap and placeholders only get written to your stylesheet if they are actually extended in your code.

Also, I think people tend to get confused about how css frameworks work and how decoupling css and html actually works.
For very large websites (or ones that you expect eventually to grow very large), where performance and css file size is crucial, some kind of OOCSS approach is your best bet. And this means inevitably that you have formatting code directly in your HTML.

If you can allow yourself to be a little less efficient and want your HTML clean, make sure to use semantic classes (examples for buttons: call-to-action, call-to-action-secondary, submit, btn-primary, btn-corporate-color, etc…)

Also remember to decouple your JS from CSS! use special classes for attaching behaviour (example js-submit, js-call-to-action, etc….)

Last but not least: don’t plan for updating your css framework. These frameworks are meant to give you a headstart, not to be your overall design solution. Extend them, adapt them, make them your own, invest in design and create your own look in order to make your app unique.
If what makes you think of updating is a worry to keep up with standard changes, better use compass mixins.


For being new to most of this, you’re on the right track; the resources you’ve been reading are excellent. But, I think the concerns you have might not be justified:

…the button won’t get the right style because sass will not apply that same rule to our custom class name…

In fact, I think you must be mistaken. According to the Sass documentation:

@extend works by inserting the extending selector (e.g. .seriousError) anywhere in the stylesheet that the extended selector (.e.g .error) appears.

See for the full code example.

Your original solution was actually correct. Use extends, but without the quotes:

.button {
  @extend .btn; //no quotes

I tested this using your example, and it works correctly. Sass copies all the selectors with “.btn” and on those newly created selectors, it replaces “.btn” with “.button”.

Also, if Sass produces too much duplication for your liking, don’t worry about it (so long as you are following best practices as pointed out by the links you posted). Duplicate code is easily compressed if the server uses gzip or the equivalent; the client shouldn’t notice any slower loading times, although it might take slightly longer to “unzip” the CSS. As for CSS selector speed, don’t worry about that either; the only case where speed matters for selectors is on the JavaScript side, particularly with jQuery. For your Sass code, simply follow best practices for maintainability (notably, modularization as you are trying to do, i.e. SMACSS) and you’ll be good to go.


Use @extend, but don’t quote selectors:

.button {
@extend .btn;

Then you’ll see that Sass extends related selectors too, like you want (.form-search .input-append .btn etc.).

… besides the bunch of extra selectors that will be added each time we extend a bootstrap class just to use a different name …

@extend works by copying selectors. If you don’t want that, you can “extend” in HTML instead — i.e. add Bootstrap’s class names. 🙂


The answers given by sam and tjklemz will help you resolve your immediate technical challenge, but it’s possible to decouple your CSS and HTML even more. I’ll give an example below, but keep in mind that this is just a quick example to demonstrate the power of mixins/extending CSS classes.

I’d also strongly recommend checking out the ZURB Foundation framework, as it is natively SASS, and designed with this style of development in mind.

For example:

    <div id="my-header">
        <h1><a href="#">My Company</a></h1>
        <h2>My Tagline</h2>
    <div id="my-main">
        <div class="my-widget">
            <h1>Widget Title</h1>
            <a>Widget Option 1</a>
            <a>Widget Option 2</a> 

With the accompanying SCSS:

//these examples wouldn't really work
//because bootstrap needs more markup
#my-header {
    @extend .navbar;
#my-header h1 {
    @extend .branding;
#my-main {
    @extend .container;

//good example
.my-widget {
    @extend .well;
    @extend .hero-unit;
.my-widget a {
    @extend .btn;

Leave a Reply

Your email address will not be published. Required fields are marked *