Guidance on how to upgrade from Bootstrap v3.x to v4.x with emphasis on major changes, what's new, and what's been removed.
Bootstrap 4 is a major rewrite of almost the entire project. The most notable changes are summarized immediately below, followed by more specific class and behavioral changes to relevant components.
Heads up! This will be in flux as work on the v4 alphas progresses. Until then consider it incomplete, and we’d love pull requests to help keep it up to date.
Here are the big ticket items you’ll want to be aware of when moving from v3 to v4.
px
to rem
as our primary CSS unit, though pixels are still used for media queries and grid behavior as viewports are not affected by type size.14px
to 16px
.480px
and below.$enable-gradients: true
).$enable-flex: true
and recompile) in the grid mixins and predefined classes.make-col-span
into make-col
for a singular mixin.sm
grid tier below 768px
for more granular control. We now have xs
, sm
, md
, lg
, and xl
. This also means every tier has been bumped up one level (so .col-md-6
in v3 is now .col-lg-6
in v4).12
at their max width.$grid-breakpoints
and $container-max-widths
) instead of a handful of separate variables. These replace the @screen-*
variables entirely and allow you to fully customize the grid tiers.@include media-breakpoint-up/down/only
. Now, instead of writing @media (min-width: @screen-sm-min) { ... }
, you can write @include media-breakpoint-up(sm) { ... }
.position: sticky
polyfill instead. See the HTML5 Please entry for details and specific polyfill recommendations.
position
styles, the polyfills might not support your use case. One option for such uses is the third-party ScrollPos-Styler library.This list highlights key changes by component between v3.x.x and v4.0.0.
New to Bootstrap 4 is the Reboot, a new stylesheet that builds on Normalize with our own somewhat opinionated reset styles. Selectors appearing in this file only use elements—there are no classes here. This isolates our reset styles from our component styles for a more modular approach. Some of the most important resets this includes are the box-sizing: border-box
change, moving from em
to rem
units on many elements, link styles, and many form element resets.
.text-
utilities to the _utilities.scss
file..page-header
as, aside from the border, all it’s styles can be applied via utilities..dl-horizontal
has been dropped. Instead, use .row
on <dl>
and use grid column classes (or mixins) on its <dt>
and <dd>
children.<blockquote>
styling has moved to classes—.blockquote
and the .blockquote-reverse
modifier..list-inline
now requires that its children list items have the new .list-inline-item
class applied to them..img-responsive
to .img-fluid
.>
selector have been removed, meaning nested tables will now automatically inherit styles from their parents. This greatly simplifies our selectors and potential customizations..table-responsive
right on the <table>
..table-condensed
to .table-sm
for consistency..table-inverse
option..table-reflow
option..thead-default
and .thead-inverse
..table-
-prefix. Hence .active
, .success
, .warning
, .danger
and .table-info
to .table-active
, .table-success
, .table-warning
, .table-danger
and .table-info
._reboot.scss
file..control-label
to .form-control-label
..input-lg
and .input-sm
to .form-control-lg
and .form-control-sm
, respectively..form-group-*
classes for simplicity’s sake. Use .form-control-*
classes instead now..help-block
and replaced it with .form-text
for block-level help text. For inline help text and other flexible options, use utility classes like .text-muted
..form-horizontal
class requirement..form-group
no longer applies styles from the .row
via mixin, so .row
is now required for horizontal grid layouts (e.g., <div class="form-group row">
)..form-control-label
class to vertically center labels with .form-control
s..btn-default
to .btn-secondary
..btn-xs
class entirely as .btn-sm
is proportionally much smaller than v3’s.button.js
jQuery plugin has been dropped. This includes the $().button(string)
and $().button('reset')
methods. We advise using a tiny bit of custom JavaScript instead, which will have the benefit of behaving exactly the way you want it to.
.btn-group-xs
class entirely given removal of .btn-xs
.<div>
s or <ul>
s now.<a>
and <button>
based dropdown items..divider
to .dropdown-divider
..dropdown-item
.<span class="caret"></span>
; this is now provided automatically via CSS’s ::after
on .dropdown-toggle
.~480px
grid breakpoint, meaning there are now five total tiers..col-{breakpoint}-{modifier}-{size}
to .{modifier}-{breakpoint}-{size}
for simpler grid classes. For example, instead of .col-md-3.col-md-push-9
it’s col-md-3.push-md-9
.make-col
and make-col-span
into a single make-col
mixin, thereby ensuring mixins and predefined classes utilize the same float/flex behaviors.a.list-group-item
with an explicit class, .list-group-item-action
, for styling link and button versions of list group items.remote
option (which could be used to automatically load and inject external content into a modal) and the corresponding loaded.bs.modal
event were removed. We recommend instead using client-side templating or a data binding framework, or calling jQuery.load yourself.>
selectors for simpler styling via un-nested classes..nav > li > a
, we use separate classes for .nav
s, .nav-item
s, and .nav-link
s. This makes your HTML more flexible while bringing along increased extensibility..navbar-form
class entirely. It’s no longer necessary..page-item
, .page-link
) are now required on the descendants of .pagination
s.pager
component entirely as it was little more than customized outline buttons..breadcrumb-item
, is now required on the descendants of .breadcrumb
s.label
to .tag
to disambiguate from the <label>
element..badge
component as it was nearly identical to labels/tags. Use the .tag-pill
modifier together with the label component instead for that rounded look.Dropped entirely for the new card component.
.panel
to .card
.panel-default
removed and no replacement.panel-group
removed and no replacement. .card-group
is not a replacement, it is different..panel-heading
to .card-header
.panel-title
to .card-header
. Depending on the desired look, you may also want to use heading elements or classes (e.g. <h3>
, .h3
) or bold elements or classes (e.g. <strong>
, <b>
, .font-weight-bold
). Note that .card-title
, while similarly named, produces a different look than .panel-title
..panel-body
to .card-block
.panel-footer
to .card-footer
.panel-primary
to .card-primary
and .card-inverse
(or use .bg-primary
on .card-header
).panel-success
to .card-success
and .card-inverse
(or use .bg-success
on .card-header
).panel-info
to .card-info
and .card-inverse
(or use .bg-info
on .card-header
).panel-warning
to .card-warning
and .card-inverse
(or use .bg-warning
on .card-header
).panel-danger
to .card-danger
and .card-inverse
(or use .bg-danger
on .card-header
)auto
placement options..item
to .carousel-item
..float-{xs,sm,md,lg,xl}-{left,right,none}
classes for responsive floats and removed .pull-left
and .pull-right
since they’re redundant to .float-xs-left
and .float-xs-right
..text-{xs,sm,md,lg,xl}-{left,center,right}
and removed the redundant .text-{left,center,right}
utilities as they are the same as the xs
variation..center-block
for the new .mx-auto
class.Bootstrap 3’s vendor prefix mixins, which were deprecated in v3.2.0, have been removed in Bootstrap 4. Since we use Autoprefixer, they’re no longer necessary.
Removed the following mixins: animation
, animation-delay
, animation-direction
, animation-duration
, animation-fill-mode
, animation-iteration-count
, animation-name
, animation-timing-function
, backface-visibility
, box-sizing
, content-columns
, hyphens
, opacity
, perspective
, perspective-origin
, rotate
, rotateX
, rotateY
, scale
, scaleX
, scaleY
, skew
, transform-origin
, transition-delay
, transition-duration
, transition-property
, transition-timing-function
, transition-transform
, translate
, translate3d
, user-select
Our documentation received an upgrade across the board as well. Here’s the low down:
example.rb
is a fork of the default highlight.rb
plugin, allowing for easier example-code handling.callout.rb
is a similar fork of that, but designed for our special docs callouts.We’ve added new components and changed some existing ones. Here are the new or updated styles.
Component | Description |
---|---|
Cards | New, more flexible component to replace v3’s panels, thumbnails, and wells. |
New navbar | Replaces the previous navbar with a new, simpler component. |
New progress bars | Replaces the old .progress <div> with a real <progress> element. |
New table variants | Adds .table-inverse , table head options, replaces .table-condensed with .table-sm , and .table-reflow . |
New utility classes |
TODO: audit new classes that didn’t exist in v3
The following components have been removed in v4.0.0.
Component | Removed from 3.x.x | 4.0.0 Equivalent |
---|---|---|
Panels | Cards | |
Thumbnails | Cards | |
Wells | Cards | |
Justified navs |
TODO: audit classes in v3 that aren’t present in v4
All @screen-
variables have been removed in v4.0.0. Use the media-breakpoint-up()
, media-breakpoint-down()
, or media-breakpoint-only()
Sass mixins or the $grid-breakpoints
Sass map instead.
The responsive utility classes have also been overhauled.
.hidden
and .show
classes have been removed because they conflicted with jQuery’s $(...).hide()
and $(...).show()
methods. Instead, try toggling the [hidden]
attribute, use inline styles like style="display: none;"
and style="display: block;"
, or toggle the .invisible
class..hidden-xs
.hidden-sm
.hidden-md
.hidden-lg
.visible-xs-block
.visible-xs-inline
.visible-xs-inline-block
.visible-sm-block
.visible-sm-inline
.visible-sm-inline-block
.visible-md-block
.visible-md-inline
.visible-md-inline-block
.visible-lg-block
.visible-lg-inline
.visible-lg-inline-block
) are gone..hidden-xs-up
.hidden-xs-down
.hidden-sm-up
.hidden-sm-down
.hidden-md-up
.hidden-md-down
.hidden-lg-up
.hidden-lg-down
..hidden-*-up
classes hide the element when the viewport is at the given breakpoint or larger (e.g. .hidden-md-up
hides an element on medium, large, and extra-large devices)..hidden-*-down
classes hide the element when the viewport is at the given breakpoint or smaller (e.g. .hidden-md-down
hides an element on extra-small, small, and medium devices).Rather than using explicit .visible-*
classes, you make an element visible by simply not hiding it at that screen size. You can combine one .hidden-*-up
class with one .hidden-*-down
class to show an element only on a given interval of screen sizes (e.g. .hidden-sm-down.hidden-xl-up
shows the element only on medium and large devices).
Note that the changes to the grid breakpoints in v4 means that you’ll need to go one breakpoint larger to achieve the same results (e.g. .hidden-md
is more similar to .hidden-lg-down
than to .hidden-md-down
). The new responsive utility classes don’t attempt to accommodate less common cases where an element’s visibility can’t be expressed as a single contiguous range of viewport sizes; you will instead need to use custom CSS in such cases.
min--moz-device-pixel-ratio
typo hack for retina media queries[disabled]
to :disabled
as IE9+ supports :disabled
. However fieldset[disabled]
is still necessary because native disabled fieldsets are still buggy in IE11.TODO: audit list of stuff in v3 that was marked as deprecated