@nauverse/tailwind-dot-grid-backgrounds weekly downloads statistics

tailwind-dot-grid-backgrounds

A tiny Tailwind CSS plugin to add customizable dot and grid backgrounds fast, in pure CSS

tl;dr • Guide and examples • Migrating from v1 • Help • Contribute

| Plugin version | Tailwind CSS | How it works | Branch |

| 2.x (latest) | ^4.0 | Pure CSS (@utility), no JavaScript | main | | 1.x | ^3.4 | JavaScript plugin | v1 (maintenance, docs) |

Still on Tailwind CSS v3? Install the v1 line: npm install --save-dev @nauverse/tailwind-dot-grid-backgrounds@1.

tl;dr

This is a Tailwind CSS v4 plugin that allows you to add background grids and background dots in an easy and customizable way.

1. Install the dependency

2. Import it in your CSS, after Tailwind CSS

3. You are done!

Try it by adding this HTML to your UI:

What

You could achieve the same by just using some Tailwind CSS code but... I found myself adding this kind of background in my projects very often. So I created a small Tailwind CSS plugin to allow me adding these backgrounds while keeping all the customization offered by Tailwind CSS.

Features

• Fully integrated with Tailwind CSS: theme colors, opacity modifiers, the spacing scale, arbitrary values and every variant (hover:, md:, dark:...) • Pure CSS: just an @import, no JavaScript and no configuration • Performant: the backgrounds are CSS gradients, and only the classes you use are generated • Zero dependencies • Tested against the latest and the oldest supported Tailwind CSS v4 releases

Guide and examples

A pattern is drawn by its color class. Its size and line (or dot) width are optional classes that you can combine with it, so each part can change on its own with variants (for example md:bg-grid-size-12).

Background grid

| Class | What it sets | Default |

| bg-grid- | Draws the grid with this line color | - | | bg-grid-size- | The size of the squares, in spacing units (like w-) | 8 (2rem) | | bg-grid-stroke- | The width of the lines, in pixels | 1 (1px) |

• accepts any theme color (neutral-950, your own --color-* variables) with an optional opacity modifier (bg-grid-blue-700/80, bg-grid-blue-700/[35%]), arbitrary values (bg-grid-[#ff0000]), CSS variables (bg-grid-(--my-color)) and current (bg-grid-current has no opacity modifier: use bg-grid-[color-mix(in_oklab,currentcolor_50%,transparent)] instead). • bg-grid-size-* also accepts --spacing-* theme keys (bg-grid-size-cell with --spacing-cell: 18px), arbitrary lengths (bg-grid-size-[18px]) and CSS variables (bg-grid-size-(--cell)). • bg-grid-stroke-* also accepts decimals (bg-grid-stroke-0.5), arbitrary lengths (bg-grid-stroke-[0.1rem]) and CSS variables (bg-grid-stroke-(--line)). • Arbitrary values are not validated, like in Tailwind CSS itself: bg-grid-[10px] generates a class that draws nothing.

Examples:

bg-grid-neutral-950 bg-grid-size-8 bg-grid-stroke-2

bg-grid-blue-700/80 bg-grid-size-48 bg-grid-stroke-8

Background dots

| Class | What it sets | Default |

| bg-dot- | Draws the dots with this color | - | | bg-dot-size- | The distance between the dots (in both axes), in spacing units | 8 (2rem) | | bg-dot-radius- | The radius of the dots, in pixels | 1 (1px) |

They accept the same values as their grid counterparts.

Examples:

bg-dot-neutral-950 bg-dot-size-8 bg-dot-radius-2

bg-dot-blue-700/80 bg-dot-size-16 bg-dot-radius-8

Customizing

Everything comes from your Tailwind CSS theme:

The pattern settings are stored in the --bg-grid-color, --bg-grid-size, --bg-grid-stroke, --bg-dot-color, --bg-dot-size and --bg-dot-radius CSS variables. They are registered with @property as non-inherited, so a pattern never leaks into the patterns of its children.

Migrating from v1

Version 2 is for Tailwind CSS v4. It is a pure CSS plugin, and each part of a pattern is now its own class.

1. Upgrade to Tailwind CSS v4 (upgrade guide). 2. Install the latest version: npm install --save-dev @nauverse/tailwind-dot-grid-backgrounds@latest. 3. Remove the plugin from your tailwind.config.* plugins (or the @plugin directive) and add @import "@nauverse/tailwind-dot-grid-backgrounds"; after @import "tailwindcss";. 4. Replace the classes. , / and keep the same values:

| v1 | v2 | | -- | -- | | bg-grid--s-- | bg-grid- bg-grid-size- bg-grid-stroke- | | bg-dot--s-- | bg-dot- bg-dot-size- bg-dot-radius- | | bg-grid-8-s-2-neutral-950 | bg-grid-neutral-950 bg-grid-size-8 bg-grid-stroke-2 | | bg-dot-16-s-8-blue-700/80 | bg-dot-blue-700/80 bg-dot-size-16 bg-dot-radius-8 | | bg-grid-px-s-1-red-500 | bg-grid-red-500 bg-grid-size-[1px] |

Sizes now follow your spacing scale (--spacing) instead of being converted to pixels, and the stroke width and dot radius default to 1px, so bg-grid- bg-grid-size- is enough for 1px lines.

Help

Thank you for using *tailwind-dot-grid-backgrounds*!

If you need any help using this plugin, feel free to create a GitHub issue, and ask your questions. I'll try to answer as quickly as possible.

Contribute

Contributions of any kind (pull requests, bug reports, feature requests, documentation, design) are more than welcome! Read the contributing guide to get started (and AGENTS.md if you use a coding agent).

Contributors

Thanks goes to these wonderful people (emoji key):

Al | Naucode 🐛 💻 📖 🚧 🚇 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

Description from the npm listing.