Bootstrap 3 Succinctly: Migrating From Version 2 to Version 3

So what’s involved in migrating from Bootstrap 2 to Bootstrap 3? In truth, not a great deal. 

Despite the many changes, there’s still not a huge amount for you to actually change, and the changes you do need to make are generally just class renames where applicable. 

One of the things you might want to do, especially if you’ve been using BS only for general web app development and not mobile or any kind of responsive design, is to disable the responsive features in BS3. 

This is easy enough to do, but not at all recommended. 

You can achieve this as follows: 

• Do not add the meta tag containing the device width and other initial sizing info to the head of your document. 
• Do override the width on your elements that are marked up with a class of container, and make sure you use style='width: xxx !important' when you do so. 
• Do make sure that any width overrides are processed after the main Bootstrap CSS rules have been loaded. 
• Do remove all collapsing and expanding behaviors and rules from all navbar constructs within your document. 
• Do change all grid layout classes to use only col-xs-* classes and none of the other four levels. 

If you’re targeting IE8 and IE9, you will still need to make sure you use respond.js, even if you do disable responsiveness as outlined. 

Class Changes

As I mentioned earlier, there have been many class name changes between the two versions, and many classes have been deprecated and withdrawn. 

One thing that will (and already has if you look at Stack Overflow) come as a surprise to many is the withdrawal of the fluid width classes. 

In version 2, if you wanted a full-width elastic container, then you had to do something like the following: 

1

<div class="container-fluid" id="myParentContainer">

2

  <div class="row-fluid" id="mycontentrow">

3

    <h1>A headline</h1>

4

    <p>Some paragraph text</p>

5

  </div>

6

</div>

In version 3 the container and row-fluid classes no longer exist. 

So how do you get a fluid container? Simple: you don’t. 

Rather than wrap your contents in a container and then a row, you simply don’t wrap them in anything. 

You can still use the grid system to provide enclosing containers for your content, so that things line up nicely with Bootstrap’s grid, but you no longer need to put a container around those collections of <div> elements before you use them. 

In fact, if you use container and row (the non-fluid versions still exist) then you’ll end up with all your content being in the 1024-pixel, central column automatically, and be able to use the entire page width if you do not. 

Migrating the Grid System 

Then next biggest class change is the grid system itself. 

In version 2 you typically created grids in the following manner: 

1

<div class="container">

2

  <div class="span2">Content here</div>

3

  <div class="span10">Content here</div>

4

</div>

This code would give you two containers that neatly filled the 12 grid squares horizontally that all layouts had (typically a side bar). 

In version 3, the “medium level” grid is now the equivalent of the v2 span classes, so to rewrite the previous code for V3 you simply do the following: 

1

<div class="container">

2

  <div class="col-md-2">Content here</div>

3

  <div class="col-md-10">Content here</div>

4

</div>

However, whereas version 2 had only one level of grid size, version 3 now has four levels. Each level is tailored for the expected main target device that you anticipate your end product will be running on. 

These grid units are now named as follows: 

• Extra small devices: col-xs-*
• Small devices: col-sm-*
• Medium devices: col-md-*
• Large devices: col-lg-*

Media queries are used internally for BS3 to decide just which of the aforementioned grid classes to use, and the different sizes are defined as follows: 

• Extra small: display width less than 768 pixels 
• Small: display width greater than or equal to 768 pixels, or less than 992 pixels 
• Medium: display width greater than or equal to 992 pixels, or less than 1,200 pixels 
• Large: display width greater than or equal to 1,200 pixels 

You can code up multiple versions of your grid for BS3 to decide which type to use when targeting multiple displays. For example if you did the following: 

1

<div class="container">

2

  <div class="col-xs-2">Content here</div>

3

  <div class="col-xs-10">Content here</div>

4

  <div class="col-sm-2">Content here</div>

5

  <div class="col-sm-10">Content here</div>

6

  <div class="col-md-2">Content here</div>

7

  <div class="col-md-10">Content here</div>

8

  <div class="col-lg-2">Content here</div>

9

  <div class="col-lg-10">Content here</div>

10

</div>

BS3 will hide and unhide the containers as required, depending on the width of the device display and the operation of the media queries. 

As with previous versions of the grid system, there are 12 columns horizontally across all the different sizes, so whichever grid size is displayed, you will always still get 12 grids on every device. 

The column width itself does change, however, so you may need to plan the content in those grids to take advantage of the differing sizes. The sizes for each of them are as follows: 

• col-xs-* = Auto sizing, no fixed dimensions 
• col-sm-* = 60 pixels 
• col-md-* = 78 pixels 
• col-lg-* = 95 pixels 

The gutter margin in all cases will remain at 15 pixels on each side of the grid container, giving an overall gutter of 30 pixels. This size will be consistent no matter which grid size level you’re using. 

Nesting and offsets work as they did previously, but as with the grids themselves, by way of a slight renaming of the actual classes used. 

To apply an offset, simply use col-md-offset-*, remembering to replace the md with xs, sm, or lg as needed, depending on your grid size. 

Nesting is done simply by nesting containers under control of the col-xx-* classes inside each other, where they will resize and behave as they did in previous BS versions. 

The following examples show the correct way to achieve both of these techniques: 

1

<div class="col-md-9">

2

  Level 1: .col-md-9

3

  <br/>

4

  <div class="col-md-6">

5

    Level 2: .col-md-6

6

  </div>

7

  <div class="col-md-6">

8

    Level 2: .col-md-6

9

  </div>

10

</div>

This example will give you a grid that looks like the following: 

1

<div class="col-md-4">

2

  .col-md-4

3

</div>

4

<div class="col-md-4 col-md-offset-4">

5

  .col-md-4 .col-md-offset-4

6

</div>

7

<div class="col-md-3 col-md-offset-3">

8

  .col-md-3 .col-md-offset-3

9

</div>

10

<div class="col-md-3 col-md-offset-3">

11

  .col-md-3 .col-md-offset-3

12

</div>

13

<div class="col-md-6 col-md-offset-3">

14

  .col-md-6 .col-md-offset-3

15

</div>

This example will give you a layout as follows: 

BS3 also brings something new to the table when it comes to offsetting and nesting, and that’s something called column ordering. 

If you want your columns to be presented in a different order to how you define them in your HTML document, then you can use the new col-xx-pull-* and col-xx-push-* classes to push or pull your grid layouts into the order you want them. For example: 

1

<div class="col-md-8">8 columns of content</div>

2

<div class="col-md-4">4 columns of content</div>

If you render those in your document, as expected, you’ll get the following: 

If, however, you modify the above code to add push and pull modifiers as follows: 

1

<div class="col-md-8 col-md-push-4">8 columns of content</div>

2

<div class="col-md-4 col-md-pull-8">4 columns of content</div>

When you render your document, you should see your layout change as follows: 

Finally, if you’re using the Less CSS source versions of Bootstrap, you have complete control over the grid sizes by changing the following variables: 

• @grid-columns: controls the number of grids horizontally (default 12) 
• @grid-gutter-width: the total margin around each grid (default 30 pixels) 
• @grid-float-breakpoint: the minimum size below which we have “extra small” devices (default 768 pixels) 

So now that we have the new grid system under control, is there anything else you need to know? 

The more astute of you may be thinking, “But that’s crazy—with all those multiple sets of <div> elements and offsets with col-xx-xx classes, all for different size displays, I might as well just create four different sites, with four different resolutions in mind!” To be honest, I wouldn’t blame you, except for one thing: each of these new layout size levels are designed to work on the same markup, at the same time, and occupy the same space. 

Let’s take the code in the previous code sample 4, and rewrite it to do this the recommended way: 

1

<div class="container">

2

  <div class="col-xs-2 col-sm-2 col-md-2 col-lg-2">Content here</div>

3

  <div class="col-xs-10 col-sm-10 col-md-10 col-lg-10">Content here</div>

4

</div>

Ok, so you might end up with the class list from hell on your elements, but one set of markup will adapt to all display sizes, and resize itself where needed. 

This also works with the various offset, order, and nesting classes.

Other Migrations  

In addition to those we’ve already discussed, the following class names also need to be changed if you’re migrating from a V2 layout to a V3 layout (Note: the following table has been taken directly from the Bootstrap 3 docs and was correct at the time of writing. As Bootstrap matures, however, this may not remain so). 

As previously mentioned, most of the changes have been made to bring conformity to the naming scheme used by the various classes. But many of them have also been renamed because their overall purpose has changed. 

We’ll go into in more detail in upcoming tutorials in this series, but for now, if you’re doing a conversion, then Table 2 will tell you everything you need in order to retarget a v2 layout to v3. 

You might want to consider using a custom job in something like a Grunt.js task, so that when you run your build system, these changes are performed automatically. This will allow your developers to remain productive using v2 while gradually making the move to v3. 

So what exactly has been added to Bootstrap that’s new, and what exactly has been removed? 

We’ll start with what’s been removed, and we’ll cover what’s been added in more detail in the tutorial on “Changed CSS features". It’s more important that you know what’s been removed in this tutorial, since this is the tutorial you’re likely to be referring to when migrating your layouts 

First we’ll start with what’s been removed where forms are concerned, and unfortunately, that’s quite a lot. We no longer have a specific type for a search form form-search, and the shaded bar typically found at the foot of a form form-actions has also been deprecated in v3. 

Also gone is the class typically used to display validation errors, control-group-info, and its help counterpart, help-inline. None of these four classes have any recommended replacement in the v3 code base, meaning that to construct equivalents of them, you will need to use other elements and classes where applicable. 

Continuing with forms, the main controls class used to wrap entire control sets is gone, along with controls-row. Instead, you are advised to use row or the new form-group class. Forms have also lost most of the sizing classes; the fixed-size classes such as input-mini, input-small, input-medium, input-large, input-xlarge, and input-xxlarge have now all gone away, along with the block level control class input-block-level. Instead, you are now advised to control your form element sizes using form-control in combination with the new sizes and layouts available in the grid system. 

From an individual control point of view, the inverse classes have been removed from buttons and other similar controls, and we’ve also lost the dropdown-submenu class in favor of just using split drop-down buttons to create the same functionality. 

For tabs, the tabs-left, tabs-right, and tabs-below classes no longer exist, which means we now only have the ability to put tabs at the top of the content, left-aligned. 

Staying with tabs, the class to work with content in a pill-based tab setup has also been removed, meaning that pill-pane and pill-content should now use the general tab-content and tab-pane classes. 

Finally, the various navbar classes are not without casualties: navbar-inner, navbar divider-vertical, nav-list, and nav-header are no longer part of the framework. 

In most cases, there are no direct equivalents in v3 for these classes, although there are some similarities in other classes that may prove useful. For example, nav-list and nav-header can be recreated using List groups. 

There’s a quick reference chart to all of these in the migration guide on the Bootstrap 3 website.

This tutorial represents a chapter from Bootstrap 3 Succinctly, a free eBook from the team at Syncfusion.