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

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

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

  3. Rename the classes

    Commit your work, then run the Perl command below. It renumbers the gutters and turns Bootstrap's col-md-6 into md:col-6.

  4. Fix what the command can't

    Change spacing utilities such as mb-3 to mb-4, swap Bootstrap's display and flex utilities for Tailwind's, and replace classes like container-md.

  5. 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-x and --bs-gutter-y, so custom CSS that reads them still works.

  • Prefix, not infix

    Bootstrap writes col-md-6. Tailwind writes md: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-3 is g-4 here. Breakpoint widths differ a little too.

The same layout, before and after

Bootstrap 5

index.html
<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

index.html
<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

Responsive classes
BootstrapHereNotes
col-md-6md:col-6Tailwind puts the breakpoint in front, as a prefix.
col-lglg:colSame for the equal-width column.
col-xl-autoxl:col-auto
offset-md-3md:offset-3
row-cols-md-3md:row-cols-3
g-md-4md:g-6The number changes too, see the gutter sizes below.
col-xxl-42xl:col-4Bootstrap's xxl is called 2xl in Tailwind.
order-md-2md:order-2order-* is Tailwind's own, and it goes up to 12.

Gutter sizes

Gutter sizes
BootstrapHereSize
g-0g-00
g-1g-10.25rem
g-2g-20.5rem
g-3g-41rem
g-4g-61.5rem
g-5g-123rem

Utilities that come from Tailwind

Utilities that come from Tailwind
BootstrapHereNotes
d-flexflex
d-none d-md-blockhidden md:block
justify-content-betweenjustify-between
align-items-centeritems-center
align-self-endself-end
mb-3, p-3mb-4, p-4Spacing 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

main.css
@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.

terminal
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

Running it a second time would renumber the gutters again. It also only knows the class names above, so spacing utilities such as 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

The plugin only adds .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.

Keep going