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 metatag containing the device width and other initial sizing info to the head of your document.

Do override the widthon 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 allnavbarconstructs within your document.

Do change all grid layout classes to use onlycol-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:

Rather than wrap your contents in a containerand 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 containerand 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.

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:

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 mdwith xs, sm, or lgas 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:

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:

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-xxclasses, 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:

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).

Bootstrap version 2 class name

Bootstrap version 3 class name

.control-group.warning.control-group.error.control-group.success

.form-group.has-*

.checkbox.inline.radio.inline

.checkbox-inline.radio-inline

.input-prepend.input-append

.input-group

.add-on

.input-group-addon

.img-polaroid

.img-thumbnail

ul.unstyled

.list-unstyled

ul.inline

.list-inline

.muted

.text-muted

.label

.label .label-default

.label-important

.label-danger

.text-error

.text-danger

.table .error

.table .danger

.bar

.progress-bar

.bar-*

.progress-bar-*

.accordion

.panel-group

.accordion-group

.panel .panel-default

.accordion-heading

.panel-heading

.accordion-body

.panel-collapse

.accordion-inner

.panel-body

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-actionshas 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 controlsclass used to wrap entire control sets is gone, along with controls-row. Instead, you are advised to use rowor 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-xxlargehave 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-controlin combination with the new sizes and layouts available in the grid system.

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

For tabs, the tabs-left, tabs-right, and tabs-belowclasses 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-paneand pill-contentshould now use the general tab-content and tab-paneclasses.

Finally, the various navbarclasses are not without casualties: navbar-inner, navbar divider-vertical, nav-list, and nav-headerare 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-listand nav-headercan be recreated using Listgroups.

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