How to Migrate Bootstrap Classes to Tailwind

Migrating from Bootstrap to Tailwind looks like a find-and-replace job. d-flex becomes flex, justify-content-between becomes justify-between, and most of the utility layer maps across almost mechanically.

Then the layout comes out subtly wrong everywhere and nobody can say why. The cause is a numbering collision that produces valid CSS with different values.

The spacing scale problem

Both frameworks use numbered spacing utilities. They mean different things.

Bootstrap’s scale is a set of steps: 0, then roughly .25rem, .5rem, 1rem, 1.5rem, 3rem for steps 1 to 5.

Tailwind’s scale is arithmetic: each step is 0.25rem, so 4 is 1rem, 8 is 2rem, and so on.

So Bootstrap’s mb-3 is 1rem. Tailwind’s mb-3 is 0.75rem. Copy the number across unchanged and every margin in the project shrinks by a quarter of a rem — enough that the page looks slightly off and not enough that anyone can point at what changed.

The correct mapping for mb-3 is mb-4. Same for every other spacing utility, and there are usually hundreds.

Note that steps 1 and 2 happen to coincide, which is exactly why the problem goes unnoticed — the first few conversions you check look correct.

Components don’t convert

Utilities map. Components don’t, because Tailwind deliberately doesn’t have any.

Bootstrap’s modal, dropdown, carousel, accordion and tooltip are markup plus JavaScript plus CSS. Tailwind provides styling primitives and nothing else, so each of those becomes either a headless component library, a hand-built implementation, or a separate dependency.

That’s the real cost of the migration, and it’s worth scoping before starting. The utility conversion is a day; replacing eleven components is not.

The grid

Bootstrap’s twelve-column row/col system maps onto Tailwind’s grid utilities, but not one-to-one. Breakpoint names differ, the default breakpoint values differ, and Bootstrap’s implicit gutters have no equivalent — Tailwind uses explicit gap.

Convert grids per breakpoint and check each one, rather than assuming a mechanical translation held.

Common mistakes to avoid

• Copying spacing numbers across unchanged, which is the collision above.
• Assuming components will convert, then discovering mid-migration that you need a modal.
• Forgetting that Bootstrap’s breakpoints and Tailwind’s defaults are different values.
• Running both frameworks simultaneously during migration, where the reset styles conflict.
• Converting class strings in JavaScript-generated markup with a regex that also hits unrelated strings.

How to do it with Bootstrap to Tailwind Converter

The Bootstrap to Tailwind Converter maps the utilities and flags what it can’t.

1. Paste the markup or class list you’re migrating.
2. Read the spacing conversions carefully — the numbers change even when they look like they shouldn’t.
3. Handle the flagged unmapped classes by hand; components have no direct equivalent.
4. Check the result at each breakpoint rather than only at desktop width.

Tailwind’s spacing scale reference is worth having open during a migration. Other developer tools are in the tools directory.

Frequently asked questions

Do Bootstrap components convert?

No. Utilities map reasonably well; components like modals, dropdowns and carousels are markup plus JavaScript, and Tailwind ships no components by design.

Why do the spacing numbers differ?

Because the scales are defined differently and happen to use overlapping integers. Steps 1 and 2 coincide, which is why the mismatch isn’t obvious until the layout looks wrong.

Is the grid a direct translation?

Roughly. The twelve-column row and col classes map onto Tailwind’s grid utilities, but breakpoint names and defaults differ, so check each breakpoint.

Final thought

Convert one page, check the spacing at every breakpoint, and only then run the rest. The scale collision is invisible in a diff and obvious on a screen.

Try the free Bootstrap to Tailwind Converter