Tailwind CSS plugin · v1.4.2

The Bootstrap grid, for Tailwind.

If you already think in rows and columns, keep doing it. tw-bootstrap-grid adds the familiar 12-column grid, .row, .col-6, .offset-2, .g-4, to Tailwind, with RTL support and no opinions about how your components should look.

$npm install tw-bootstrap-grid

What you get

  • 12-column grid

    .row, .col, .col-auto and .col-1 to .col-12, just like Bootstrap.

  • Gutters from your theme

    .g-*, .gx-* and .gy-* use your Tailwind spacing scale, so they match the rest of your design.

  • Offsets

    .offset-0 to .offset-12 to center a column or leave a gap.

  • Row columns

    .row-cols-1 to .row-cols-6 and .row-cols-auto size every child from one class on the row.

  • Containers

    .container and .container-fluid with gutter-aware padding. Max widths come from Tailwind's own breakpoints.

  • Responsive and RTL

    Every class takes Tailwind's breakpoint prefixes, like md:col-6, and flips correctly with dir="rtl".

It only does layout: no colors, no components, no resets. It adds to Tailwind rather than replacing any of it, so you can mix col-4 and flex on the same page without a second thought.

Getting started

Installation

Three steps: install the package, register the plugin, start using the classes.

1Install the package

npm install tw-bootstrap-grid

2Register the plugin

Pick your Tailwind version in the header and the snippet below follows. Tailwind v4 registers plugins in CSS, v3 in the config file.

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid";

In a CommonJS v3 config, plugins: [require("tw-bootstrap-grid")] works as well.

3Use the classes

That's it. Use them in your markup like any other Tailwind class. Anything you can do with sm:, md: or hover: works here too.

index.html
<div class="container">
  <div class="row g-4">
    <div class="col-12 md:col-6 lg:col-4">One</div>
    <div class="col-12 md:col-6 lg:col-4">Two</div>
    <div class="col-12 lg:col-4">Three</div>
  </div>
</div>

You need a build step

The plugin runs inside Tailwind's compiler (PostCSS, Vite, Webpack, the Tailwind CLI…). It can't work with the Tailwind Play CDN script, which has no way to load plugins from npm.

Getting started

Configuration

The defaults match Bootstrap, so you can skip this page. Come back when you want different breakpoints or gutter sizes.

Breakpoints

The plugin has no breakpoints of its own. Prefixes like md:col-6 and the max-width of .container both come from Tailwind, so changing your screens changes the grid with them.

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid";

@theme {
  --breakpoint-sm: 40rem;  /* 640px */
  --breakpoint-md: 48rem;  /* 768px */
  --breakpoint-lg: 64rem;  /* 1024px */
  --breakpoint-xl: 80rem;  /* 1280px */
  --breakpoint-2xl: 96rem; /* 1536px */
}

Gutter sizes

Gutters are the space between columns. By default it's 1.5rem horizontally and 0 vertically. Set it once for everything, or separately for containers and rows. In v3 you pass options to the plugin, in v4 you set CSS variables.

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid";

:root {
  /* used by containers and rows */
  --bs-global-gutter-x: 1.5rem;
  --bs-global-gutter-y: 0;

  /* overrides for one of them only */
  --bs-container-gutter-x: 1rem;
  --bs-row-gutter-x: 2rem;
  --bs-row-gutter-y: 1rem;
}
Gutter resolution order
PriorityCSS variableOptionNotes
1--bs-row-gutter-x / --bs-container-gutter-xrowGutters / containerGuttersThe most specific value wins.
2--bs-global-gutter-xguttersShared fallback for both.
31.5rem (x) and 0 (y)built-in defaultThe same defaults Bootstrap uses.

The CSS variables are read at runtime, so in either version you can also override them on any element to change the gutters for just that section. For a single row, use .g-*, .gx-* and .gy-*.

Turn off the containers

Prefer Tailwind's own container alone? Set generateContainers to false and the plugin stops generating .container-fluid and its gutter-aware padding. Rows and columns are unaffected.

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid" {
  generateContainers: false;
}

Why variables in v4?

Tailwind v4 can pass simple values like generateContainers: false; to a plugin, but not nested objects such as gutters. CSS variables cover that case and have the bonus of being overridable per element.

Reference

Classes

Everything the plugin adds, in one place.

Layout

Layout classes
ClassWhat it doesNotes
.containerwidth: 100%; centered; padding from the gutterMax width comes from Tailwind's breakpoints.
.container-fluidsame as .containerFull width at every breakpoint.
.rowdisplay: flex; flex-wrap: wrap; negative marginsCancels the outer gutter and lays out its children.

Columns

Columns classes
ClassWhat it doesNotes
.colflex: 1 0 0%Shares the remaining space equally.
.col-autoflex: 0 0 auto; width: autoSized by its content.
.col-1 … .col-12flex: 0 0 auto; width: n / 12Takes n of 12 slots.

Offsets and row columns

Offsets and row columns classes
ClassWhat it doesNotes
.offset-0 … .offset-12margin-inline-start: n / 12Flips automatically in RTL.
.row-cols-1 … .row-cols-6children get width: 1 / nSet on the .row, applies to every child.
.row-cols-autochildren get width: autoChildren are sized by content.

Gutters

Gutters classes
ClassWhat it doesNotes
.g-*--bs-gutter-x and --bs-gutter-yBoth directions.
.gx-*--bs-gutter-xHorizontal only.
.gy-*--bs-gutter-yVertical only.

Everything is responsive

Add a breakpoint prefix to any class above: md:col-6, lg:offset-3, sm:row-cols-2, xl:g-8.

Which gutter steps exist?

.g-*, .gx-* and .gy-* are built from your spacing theme. In v3 that's every key of theme.spacing without a dot (so g-4 yes, g-0.5 no). In v4 it's the default scale, g-0 to g-96 and g-px.

Alignment and order come from Tailwind

The plugin doesn't ship its own justify-*, items-* or order-*. A .row is a regular flex container, so Tailwind's utilities work on it directly.

Coming from Bootstrap

Migrating from Bootstrap

The grid works the way you remember. Three things look different: how responsive classes are written, the spacing numbers, and the breakpoint widths.

  • 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 full guide has the class mapping tables, the gutter size changes, how to match Bootstrap's breakpoints and a command that converts your markup.

Read the migration guide

Usage

Examples

Every example is live. Edit the HTML on the left and the preview updates as you type. If you know the Bootstrap grid (opens in a new tab), this will feel familiar.

A basic layout

A .container centers your content, a .row lines columns up side by side, and each .col-* takes that many of the 12 available slots. Two col-6 columns split the row in half.

Preview
Editable HTML
<div class="container">
  <div class="row">
    <div class="col-6">col-6</div>
    <div class="col-6">col-6</div>
  </div>
  <div class="row">
    <div class="col-4">col-4</div>
    <div class="col-4">col-4</div>
    <div class="col-4">col-4</div>
  </div>
</div>

Columns always wrap. Anything past 12 slots in a single row drops down to the next line, which is handy for card lists.

Equal and auto-width columns

A bare .col shares whatever space is left, so three of them are three equal columns. .col-auto sizes itself to its content, and the neighbouring .col takes the rest.

Preview
Editable HTML
<div class="container">
  <div class="row">
    <div class="col">col</div>
    <div class="col">col</div>
    <div class="col">col</div>
  </div>
  <div class="row">
    <div class="col-auto">col-auto</div>
    <div class="col">col (fills the rest)</div>
    <div class="col-auto">auto</div>
  </div>
</div>

Responsive columns

Every class takes Tailwind's breakpoint prefixes. Start mobile-first with col-12, then change the width at larger screens with sm:, md:, lg: and so on. Use the width buttons above the preview to see each breakpoint kick in.

Preview
768px · md · 0%
Editable HTML
<div class="container">
  <div class="row">
    <div class="col-12 md:col-8">col-12 md:col-8</div>
    <div class="col-12 md:col-4">col-12 md:col-4</div>
  </div>
  <div class="row">
    <div class="col-6 lg:col-3">1</div>
    <div class="col-6 lg:col-3">2</div>
    <div class="col-6 lg:col-3">3</div>
    <div class="col-6 lg:col-3">4</div>
  </div>
</div>

The preview is a real viewport. It shows the width and breakpoint in the corner, and the phone, tablet and desktop buttons switch it, so md: and lg: apply just as they would on that screen.

Gutters

Gutters are the gaps between columns. .g-* sets both directions, .gx-* only horizontal and .gy-* only vertical. The numbers come from Tailwind's spacing scale, so g-4 is the same step as p-4.

Preview
Editable HTML
<div class="container">
  <div class="row g-0">
    <div class="col-6">g-0</div>
    <div class="col-6">g-0</div>
  </div>
  <div class="row g-4">
    <div class="col-6">g-4</div>
    <div class="col-6">g-4</div>
    <div class="col-6">g-4</div>
    <div class="col-6">g-4</div>
  </div>
  <div class="row gx-10 gy-2">
    <div class="col-6">gx-10 gy-2</div>
    <div class="col-6">gx-10 gy-2</div>
    <div class="col-6">gx-10 gy-2</div>
    <div class="col-6">gx-10 gy-2</div>
  </div>
</div>

Put gutter classes on the .row. Use g-0 to remove the gaps completely.

Offsets

.offset-* pushes a column over by that many slots. It's the quick way to center a column or leave a gap. Offsets work with breakpoint prefixes too, like lg:offset-3.

Preview
Editable HTML
<div class="container">
  <div class="row">
    <div class="col-6 offset-3">col-6 offset-3 (centered)</div>
  </div>
  <div class="row">
    <div class="col-4">col-4</div>
    <div class="col-4 offset-4">col-4 offset-4</div>
  </div>
  <div class="row">
    <div class="col-12 md:col-8 md:offset-2">col-12 md:col-8 md:offset-2</div>
  </div>
</div>

Offsets use margin-inline-start, so they push from the correct side when the page is right-to-left. Try the RTL button above the preview.

Row columns

When every column is the same size, set it once on the row instead of on each child. .row-cols-1 to .row-cols-6 give each child an equal share, and .row-cols-auto sizes them by content.

Preview
Editable HTML
<div class="container">
  <div class="row row-cols-2 lg:row-cols-3">
    <div class="col">1</div>
    <div class="col">2</div>
    <div class="col">3</div>
    <div class="col">4</div>
    <div class="col">5</div>
    <div class="col">6</div>
  </div>
</div>

Combine it with breakpoints to change the column count as the screen grows, for example row-cols-2 lg:row-cols-3.

Nesting

A column can hold its own .row. The nested row starts a fresh 12-slot grid inside the column, so you can split a space as many times as you need.

Preview
Editable HTML
<div class="container">
  <div class="row">
    <div class="col-12 md:col-8">
      col-12 md:col-8
      <div class="row mt-3">
        <div class="col-6">nested col-6</div>
        <div class="col-6">nested col-6</div>
      </div>
    </div>
    <div class="col-12 md:col-4">col-12 md:col-4</div>
  </div>
</div>

Alignment and order

A .row is a normal flex container, so Tailwind's own flexbox utilities work on it: items-*, justify-*, self-* and order-*. The plugin doesn't redefine them.

Preview
Editable HTML
<div class="container">
  <div class="row items-center justify-center" style="min-height: 7rem">
    <div class="col-3">items-center</div>
    <div class="col-3" style="padding-block: 2rem">taller</div>
    <div class="col-3">justify-center</div>
  </div>
  <div class="row">
    <div class="col-4 order-3">1 (order-3)</div>
    <div class="col-4 order-1">2 (order-1)</div>
    <div class="col-4 order-2">3 (order-2)</div>
  </div>
</div>

order-2 md:order-1 style swaps are a common pattern: stack in one order on phones, flip them on larger screens.

Right-to-left

Set dir="rtl" on the container, or on <html> for the whole page, and the grid flows from the right. This is the one to use for Arabic, Persian, Hebrew and other RTL languages.

Preview
Editable HTML
<div class="container" dir="rtl">
  <div class="row">
    <div class="col-4">1</div>
    <div class="col-4">2</div>
    <div class="col-4">3</div>
  </div>
  <div class="row">
    <div class="col-6 offset-3">offset-3 starts from the right</div>
  </div>
</div>

Nothing to configure. The row's gutters are symmetric and offsets use logical properties, so they flip on their own.

Good to know

Right-to-left

Add dir="rtl" and the grid mirrors itself. There is nothing to configure.

For the whole page

index.html
<html dir="rtl">
  ...
</html>

For one section

index.html
<div class="container" dir="rtl">
  <div class="row">
    <div class="col-6 offset-3">Starts from the right</div>
  </div>
</div>

Why it just works

Offsets use margin-inline-start, and the row's negative margins and the columns' padding are symmetric, so they flip on their own. Use the RTL button on any example above to see it.

Good to know

Frequently asked questions

Answers to the questions that come up most.

No. Tailwind's container keeps providing the per-breakpoint max widths. The plugin adds centering and gutter-aware padding on top. If you'd rather not have that, set generateContainers to false.

Yes, that's the idea. A .row is a flex container, so items-center, justify-between, order-2, mt-4 and the rest apply to it and to its columns as usual.

Tailwind only generates CSS for classes it can find in your source files. In your own project that's automatic. On this page the editable examples can contain anything, so the demo pre-generates every plugin class and breakpoint.

No. The CDN script can't load plugins from npm. Use a build setup such as Vite, PostCSS, Webpack or the Tailwind CLI.

Tailwind v3.4 and v4, on Node 18 or newer. The package ships ESM and CommonJS builds with TypeScript types.

The class names are close: col-md-6 becomes md:col-6, and gutter numbers follow Tailwind's scale. The migration guide has the full mapping and a command that converts your markup.

Found a bug or have an idea?

Please open an issue (opens in a new tab) or send a pull request (opens in a new tab) on GitHub. Small fixes and documentation improvements are very welcome.