tw-bootstrap-grid
TypeScript icon, indicating that this package has built-in type declarations

1.2.3 • Public • Published

tw-bootstrap-grid

npm version bundle size npm downloads license RTL Support

A Tailwind CSS plugin that brings a responsive, Bootstrap-like grid system to Tailwind, complete with rows, columns, gutters, offsets, and ordering utilities.

📌 This plugin supports Tailwind CSS v3 and v4.
🌐 Includes full RTL (Right-to-Left) support for layouts in languages like Arabic, Hebrew, and Persian.


✨ Features

  • 🧱 .row, .col, .col-1 to .col-12 for flexible column layouts
  • 🧩 .g-*, .gx-*, .gy-* for gutter spacing (uses Tailwind spacing scale)
  • 📏 .offset-* to add horizontal column offsets
  • 🔀 .order-*, .order-first, .order-last for reordering flex items
  • 📦 .container, .container-fluid with responsive max-widths

📦 Installation

Install the plugin via NPM:

npm install tw-bootstrap-grid

or with Yarn:

yarn add tw-bootstrap-grid

⚙️ Usage

✅ 1. Tailwind Config (tailwind.config.js / tailwind.config.ts)

import TailwindBootstrapGrid from "tw-bootstrap-grid";

export default {
    content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
    theme: {
        extend: {},
    },
    plugins: [TailwindBootstrapGrid],
};

✅ 2. CSS / PostCSS Plugin Usage (Tailwind v4 only)

If you're using Tailwind via CSS (e.g., with PostCSS or Vite), you can import the plugin directly:

@import "tailwindcss";
@plugin "tw-bootstrap-grid";

✅ The plugin will automatically be resolved from node_modules.


🎛️ Customizing Breakpoints

You can override the default container breakpoints in two ways:

✅ Option 1: Using CSS @theme directive (Tailwind v4 only)

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

⚠️ Requires Tailwind CSS v4


✅ Option 2: Via Tailwind Config (tailwind.config.js / tailwind.config.ts)

import TailwindBootstrapGrid from "tw-bootstrap-grid";

export default {
    content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
    theme: {
        screens: {
            sm: "40rem", // 640px
            md: "48rem", // 768px
            lg: "64rem", // 1024px
            xl: "80rem", // 1280px
            xxl: "96rem", // 1536px
        },
        extend: {},
    },
    plugins: [TailwindBootstrapGrid],
};

✅ Compatible with both Tailwind v3 and v4.
The plugin will automatically use these values to generate responsive container max-widths.


🎛️ Customizing Gutters

This plugin provides flexible ways to configure horizontal (x) and vertical (y) gutters:

✅ Option 1: Via Tailwind Config (tailwind.config.js / tailwind.config.ts)

You can configure gutter behavior directly through plugin options when adding the plugin:

import TailwindBootstrapGrid from "tw-bootstrap-grid";

export default {
    content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
    plugins: [
        TailwindBootstrapGrid({
            // shared gutter values used when no specific values are set for container or row
            gutters: {
                x: "1.5rem",
                y: "0",
            },
            // specific gutter values for `.container`
            // overrides `gutters` if provided
            containerGutters: {
                x: "1.5rem", // used instead of gutters.x
                // y not provided → falls back to gutters.y or default ("0")
            },
            // specific gutter values for `.row`
            // overrides `gutters` if provided
            rowGutters: {
                // x not provided → falls back to gutters.x or default ("1.5rem")
                y: "0", // overrides gutters.y
            },
        }),
    ],
};

Priority:

Target Element Priority Order
.container 1️⃣ containerGutters → 2️⃣ gutters → 3️⃣ Default (1.5rem / 0)
.row 1️⃣ rowGutters → 2️⃣ gutters → 3️⃣ Default (1.5rem / 0)

✅ Compatible with both Tailwind v3 and v4.


✅ Option 2: Using CSS @theme directive (Tailwind v4 only)

Tailwind CSS v4 introduces native CSS variable theming using @theme. You can declare gutter variables directly in your CSS:

@theme {
    --bs-global-gutter-x: 1.5rem;
    --bs-global-gutter-y: 0;

    --bs-container-gutter-x: var(--bs-global-gutter-x);
    --bs-container-gutter-y: var(--bs-global-gutter-y);

    --bs-row-gutter-x: var(--bs-global-gutter-x);
    --bs-row-gutter-y: var(--bs-global-gutter-y);
}

This approach is ideal when you want to control spacing purely from CSS or dynamically change gutter values in different themes/modes.

Priority:

Variable Fallback Chain
--bs-container-gutter-x --bs-global-gutter-x1.5rem
--bs-container-gutter-y --bs-global-gutter-y0
--bs-row-gutter-x --bs-global-gutter-x1.5rem
--bs-row-gutter-y --bs-global-gutter-y0

⚠️ This method requires Tailwind CSS v4


🧠 How It Works

Each component uses a fallback chain like:

--bs-container-gutter-x → --bs-global-gutter-x → 1.5rem
--bs-row-gutter-y       → --bs-global-gutter-y → 0
  • containerGutters and rowGutters always take top priority.
  • If not defined, it falls back to gutters.
  • If gutters is not defined, hardcoded defaults are used (1.5rem for x, 0 for y).
  • In Tailwind v4, CSS custom properties are resolved similarly.

This makes it easy to maintain consistent spacing across your layout while allowing overrides at any layer.


🧱 Examples

🔹 Basic Grid

<div class="container">
    <div class="row">
        <div class="col-6">Left</div>
        <div class="col-6">Right</div>
    </div>
</div>

🔹 RTL Example

<div class="container" dir="rtl">
    <div class="row">
        <div class="col-4 offset-4">Right-Aligned Box</div>
        <div class="col-4">Left Box</div>
    </div>
</div>

offset-*, .row, and .container classes automatically adapt to dir="rtl", making layouts RTL-friendly without extra configuration.


🔹 Responsive Columns

<div class="row">
    <div class="col-12 md:col-6">50% on md and above</div>
    <div class="col-12 md:col-6">50% on md and above</div>
</div>

This demonstrates how you can use Tailwind’s responsive syntax (sm:, md:, etc.) in place of Bootstrap’s col-sm-*, col-md-* conventions, while keeping the layout responsive and Tailwind-native.


🔹 Offset Usage

<div class="row">
    <div class="col-4 offset-4">Centered Column</div>
</div>

🔹 Order Usage

<div class="row">
    <div class="col-6 order-2 order-md-1">Second on mobile, first on desktop</div>
    <div class="col-6 order-1 order-md-2">First on mobile, second on desktop</div>
</div>

📘 Generated Utility Classes

Class Description
.row Flex container with horizontal and vertical gutters
.col Auto-width column (flex: 1 0 0%)
.col-{1-12} Fixed-width column (1–12 / 12 fraction)
.offset-{1-12} Adds left/right margin offset based on direction
.order-{0-12} Sets flex item order
.order-first Pushes item to the beginning
.order-last Pushes item to the end
.g-{key} Sets both X and Y gutters
.gx-{key} Sets only horizontal gutter
.gy-{key} Sets only vertical gutter
.container Fixed-width responsive container
.container-fluid Full-width container with padding

🧠 Notes

  • The plugin does not override any core Tailwind utility.
  • All grid utilities support responsive variants (sm:, md:, lg:, etc).
  • Gutters are handled using CSS custom properties: --theme-gutter-x and --theme-gutter-y.
  • Fully RTL-compatible: all directional utilities (offset, container, row) adapt automatically to dir="rtl".
  • This plugin is not compatible with Tailwind via CDN. Use it in a build environment (PostCSS, Vite, Webpack, etc.).

🤝 Contributing

Found a bug or have a feature request? Feel free to open an issue or submit a pull request!


🪪 License

MIT © Baver Bozdağ

Package Sidebar

Install

npm i tw-bootstrap-grid

Weekly Downloads

641

Version

1.2.3

License

MIT

Unpacked Size

18.3 kB

Total Files

7

Last publish

Collaborators

  • bawerbozdag