Guide
Migrating a Bootstrap grid to Tailwind CSS
Moving a layout from Bootstrap's grid to Tailwind takes five steps and, for most of it, one command. This guide covers what changes, how the classes map across, and the few things a script can't do for you.
Migration in five steps
Install the plugin
Install tw-bootstrap-grid and register it in your Tailwind setup. The installation guide has the snippets for Tailwind v3 and v4.
Match Bootstrap's breakpoints (optional)
If you want layouts to switch at the same widths as before, set Tailwind's screens to 576, 768, 992, 1200 and 1400px. See the breakpoints below.
Rename the classes
Commit your work, then run the Perl command below. It renumbers the gutters and turns Bootstrap's
col-md-6intomd:col-6.Fix what the command can't
Change spacing utilities such as
mb-3tomb-4, swap Bootstrap's display and flex utilities for Tailwind's, and replace classes likecontainer-md.Remove Bootstrap's CSS and check the result
Take out the Bootstrap stylesheet, then look through your pages at phone, tablet and desktop widths.
What changes, and what doesn't
What stays the same
The structure:
.container,.row,.col-*,.offset-*,.row-cols-*. Even the CSS variables keep their names,--bs-gutter-xand--bs-gutter-y, so custom CSS that reads them still works.Prefix, not infix
Bootstrap writes
col-md-6. Tailwind writesmd:col-6. This is the change you will touch most, and a script can do it for you.Different numbers
Gutter and spacing numbers follow Tailwind's scale, so Bootstrap's
g-3isg-4here. Breakpoint widths differ a little too.
The same layout, before and after
Bootstrap 5
<div class="container">
<div class="row g-3">
<div class="col-12 col-md-6 col-lg-4">A</div>
<div class="col-12 col-md-6 col-lg-4">B</div>
<div class="col-12 col-md-12 col-lg-4">C</div>
</div>
</div>tw-bootstrap-grid
<div class="container">
<div class="row g-4">
<div class="col-12 md:col-6 lg:col-4">A</div>
<div class="col-12 md:col-6 lg:col-4">B</div>
<div class="col-12 md:col-12 lg:col-4">C</div>
</div>
</div>Class mapping
Responsive classes
| Bootstrap | Here | Notes |
|---|---|---|
col-md-6 | md:col-6 | Tailwind puts the breakpoint in front, as a prefix. |
col-lg | lg:col | Same for the equal-width column. |
col-xl-auto | xl:col-auto | |
offset-md-3 | md:offset-3 | |
row-cols-md-3 | md:row-cols-3 | |
g-md-4 | md:g-6 | The number changes too, see the gutter sizes below. |
col-xxl-4 | 2xl:col-4 | Bootstrap's xxl is called 2xl in Tailwind. |
order-md-2 | md:order-2 | order-* is Tailwind's own, and it goes up to 12. |
Gutter sizes
| Bootstrap | Here | Size |
|---|---|---|
g-0 | g-0 | 0 |
g-1 | g-1 | 0.25rem |
g-2 | g-2 | 0.5rem |
g-3 | g-4 | 1rem |
g-4 | g-6 | 1.5rem |
g-5 | g-12 | 3rem |
Utilities that come from Tailwind
| Bootstrap | Here | Notes |
|---|---|---|
d-flex | flex | |
d-none d-md-block | hidden md:block | |
justify-content-between | justify-between | |
align-items-center | items-center | |
align-self-end | self-end | |
mb-3, p-3 | mb-4, p-4 | Spacing utilities shift the same way as gutters. |
Match Bootstrap's breakpoints
Bootstrap's breakpoints are 576, 768, 992, 1200 and 1400px. Tailwind's are 640, 768, 1024, 1280 and 1536px, so a layout can switch a little earlier or later after migrating. If that matters, set Tailwind's screens to Bootstrap's values.
Tailwind v4
@import "tailwindcss";
@plugin "tw-bootstrap-grid";
@theme {
--breakpoint-sm: 36rem; /* 576px */
--breakpoint-md: 48rem; /* 768px */
--breakpoint-lg: 62rem; /* 992px */
--breakpoint-xl: 75rem; /* 1200px */
--breakpoint-2xl: 87.5rem; /* 1400px */
}Tailwind's container is as wide as the breakpoint it sits on, so its max widths become 576, 768, 992, 1200 and 1400px. That is close to Bootstrap's 540, 720, 960, 1140 and 1320px, but not identical.
Rename in bulk
This Perl command renumbers the gutters and turns col-md-6 into md:col-6, col-xxl-4 into 2xl:col-4 and the old no-gutters into g-0. It rewrites the files in place, so commit first and read the diff afterwards.
perl -pi -e '
s/\b(g|gx|gy)-((?:sm|md|lg|xl|xxl)-)?([345])\b/"$1-".($2\/\/"").{3=>4,4=>6,5=>12}->{$3}/ge;
s/\bno-gutters\b/g-0/g;
s/\b(col|offset|order|row-cols|g|gx|gy)-(sm|md|lg|xl|xxl)(-([0-9]+|auto|first|last))?\b/$2:$1$3/g;
s/\bxxl:/2xl:/g;
' $(git ls-files '*.html' '*.jsx' '*.tsx' '*.vue' '*.svelte')Run it once, and check the result
mb-3 or p-3 need a manual pass, and the pattern matches any text that looks like a class, including inside comments.What doesn't carry over
.container and .container-fluid, so Bootstrap's .container-sm, .container-md and the other responsive containers are not included. Build them with Tailwind's max-w-* utilities if you need them. Bootstrap's other utilities (display, flex, spacing, text) are replaced by Tailwind's own, as in the last table above.