Tailwind CSS Cheat Sheet

1Install & importv4 setup

npm install tailwindcss @tailwindcss/vite★
The Vite plugin is the recommended path. Add it in vite.config.js: import tailwindcss from "@tailwindcss/vite" → plugins:[tailwindcss()]. Massively faster than v3.
/* your main .css file — this ONE line replaces v3's three directives */ @import "tailwindcss";★
Everything comes from a single import — no more @tailwind base/components/utilities. ⚠️ v4 auto-detects your template files, so there's no content array to configure.
# PostCSS instead: npm i @tailwindcss/postcss → postcss.config # CLI instead: npx @tailwindcss/cli -i in.css -o out.css --watch
Not on Vite? Use the PostCSS plugin (@tailwindcss/postcss) or the standalone CLI. Same @import in all three.
<div class="flex items-center gap-4 p-6 bg-white rounded-lg shadow">★
The whole idea: compose small single-purpose utilities in class. No separate CSS file to maintain, no naming things.

2@theme configCSS-first

@import "tailwindcss"; @theme { --color-brand: oklch(0.62 0.19 260); --font-display: "Satoshi", sans-serif; --breakpoint-3xl: 120rem; }★
Configure the design system in CSS via @theme — this is the headline v4 change. Each token both sets a CSS variable and generates utilities.
/* the token above auto-creates: */ bg-brand text-brand font-display 3xl:*★
Define --color-brand → get bg-brand, text-brand, border-brand, etc. for free. Namespaces: --color-*, --font-*, --spacing-*, --breakpoint-*, --radius-*, …
.hero { background: var(--color-brand); } /* tokens are real CSS vars */
Every theme value is exposed as a native custom property at runtime — use them in hand-written CSS, inline styles, or JS. --spacing drives the whole numeric scale.
@import "tailwindcss" prefix(tw); /* → tw:flex tw:p-4 */
Need a prefix (e.g. embedding in another app)? Set it on the import. A JS config is still supported via @config "./tailwind.config.js"; when you need it.

3Layout: flex & gridstructure

flex items-center justify-between gap-4★
Flexbox essentials: flex/flex-col, align on the cross axis (items-*), distribute on the main axis (justify-*), and gap-* for spacing between children.
grid grid-cols-3 gap-6 · col-span-2 row-span-1★
CSS Grid: fixed tracks with grid-cols-N, place items with col-span-*/col-start-*. Combine with responsive prefixes for adaptive layouts.
relative absolute inset-0 top-4 z-10 · hidden block inline-flex
Positioning (relative/absolute/sticky + inset/top/left + z-*) and display utilities. container centers & caps width at each breakpoint.
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">★
The bread-and-butter responsive grid — one column on mobile, widening at each breakpoint. This composition is most of real-world layout.

4Spacing & sizingthe scale

p-4 px-6 pt-2 m-4 mx-auto -mt-2★
Padding/margin: p/m + side (t r b l, x, y) + step. mx-auto centers a fixed-width block; negative margins with a - prefix.
w-64 h-screen min-w-0 max-w-prose size-10★
Sizing: w-*/h-* (fixed, full, screen, dvh, fractions like w-1/2), plus min-/max-. size-* sets width & height together.
space-y-4 /* margin between stacked children */
space-x/y-* adds gaps between siblings without touching the parent's own padding — handy when gap doesn't apply (non-flex/grid).
/* the scale is 0.25rem × n: p-4 = 1rem = 16px. one token drives it all */
Every step is calc(var(--spacing) * n). Change --spacing once in @theme and the entire scale rescales consistently.

5Typography & colorlook & feel

text-lg font-semibold leading-tight tracking-tight text-center★
Type: size (text-xs…text-9xl), font-* weight, leading-* line-height, tracking-* letter-spacing, alignment, truncate/line-clamp-3.
text-gray-700 bg-blue-500 border-gray-200★
Colors are <utility>-<name>-<shade> across a 50–950 scale (v4 palette is OKLCH — more vivid on modern displays).
bg-black/50 text-white/70 /* opacity via slash */★
Append /NN for opacity — works on any color utility (implemented with color-mix in v4). No separate opacity utility needed.
rounded-lg border shadow-md ring-2 ring-blue-500 transition
Borders/effects: rounded-*, border[-*], shadow-*, focus ring-*, and transition/duration-*/ease-* for animation.

6Responsive breakpointsmobile-first

<div class="text-base md:text-lg lg:text-xl">★
Prefix any utility with a breakpoint to apply it at that width and up. Unprefixed = all sizes. Defaults: sm 40rem, md 48rem, lg 64rem, xl 80rem, 2xl 96rem.
/* Tailwind is MOBILE-FIRST: `md:` means md and ABOVE, not "only md" */gotcha
Style the base (mobile) case unprefixed, then layer overrides upward. Writing sm: for phones is the #1 beginner mistake — the smallest style is the unprefixed one.
max-md:hidden md:max-lg:flex /* ranged / max-width */
Use max-* for a max-width query, or stack md:max-lg: to target a single range.

7State & dark variantsconditional styling

hover:bg-blue-600 focus:ring-2 active:scale-95 disabled:opacity-50★
Interaction states are just prefixes. Also focus-visible:, focus-within:, aria-*:, data-[state=open]:.
dark:bg-gray-900 dark:text-gray-100★
dark: follows the OS by default (prefers-color-scheme). For a manual class toggle, opt in with @custom-variant dark (&:where(.dark, .dark *)); then toggle .dark on <html>.
group group-hover:opacity-100 peer peer-checked:block★
Style a child off a parent's state (group + group-hover:) or off a sibling (peer + peer-checked:) — e.g. show a dropdown when the parent is hovered.
first:pt-0 last:border-0 odd:bg-gray-50 before:content-['']
Structural & pseudo-element variants: first/last/odd/even, before:/after: (pair with content-*), *: for direct children.

8Container queriesbuilt-in in v4

<div class="@container"> <div class="@md:flex @lg:grid-cols-3">★v4 core
Size a component to its container, not the viewport. Mark a parent @container, then use @sm:/@md:/@lg: on descendants — no plugin needed in v4.
@max-md:flex-col @min-[475px]:grid /* max & arbitrary sizes */
Same max-width and arbitrary-value power as viewport breakpoints, scoped to the container. Perfect for reusable cards that adapt wherever they're placed.
@container/sidebar @lg/sidebar:block /* named containers */
Name a container to target it specifically from deeper elements — useful with nested containers.

9Arbitrary values & @applyone-offs

top-[117px] bg-[#1da1f2] grid-cols-[1fr_500px_2fr] text-[clamp(1rem,2vw,2rem)]★
Arbitrary values in square brackets when the scale doesn't have what you need — any CSS value works. Use _ for spaces inside the brackets.
[mask-type:luminance] [&:nth-child(3)]:underline
Arbitrary properties ([prop:value]) for utilities that don't exist, and arbitrary variants ([&selector]:) for one-off selectors — the ultimate escape hatch.
.btn { @apply px-4 py-2 rounded-lg bg-brand text-white; }★
@apply inlines utilities into a custom class — use sparingly for genuinely repeated patterns (buttons, form controls). ⚠️ Over-using it recreates the CSS-file problem Tailwind avoids; prefer component abstractions.
/* NEVER build class names by string concat: `text-${color}-500` */gotcha
The scanner only sees complete, static class strings in source. Dynamic names get purged. Map to full literals: { red: "text-red-500", blue: "text-blue-500" }[color].

10Custom utilities & variants@utility · @variant

@utility content-auto { content-visibility: auto; }★v4
@utility registers your own utility (replaces v3's @layer utilities) — it participates in variants, so hover:content-auto works automatically.
@custom-variant pointer-coarse (@media (pointer: coarse));
@custom-variant defines a new prefix you can stack like any built-in. This is how you set up class-based dark:, theme states, etc.
@variant dark { /* styles for dark mode */ } /* apply a variant in CSS */
@variant applies an existing variant's condition inside your own CSS rule — the CSS-side counterpart to a dark: prefix.

11Directives & functionsthe @-rules

@import "tailwindcss" · @theme · @utility · @variant / @custom-variant · @apply★
The v4 directive set. Plus @source to point the scanner at extra files, and @config to load a legacy JS config.
margin: --spacing(4); width: calc(100% - --spacing(2));
The --spacing() function returns a value from your spacing scale inside hand-written CSS — stay consistent with the utilities.
color: theme(--color-brand); /* or just var(--color-brand) */
theme() reads a config value; in v4 you can usually reach for the CSS variable directly (var(--color-*)) since tokens are variables.
@source "../node_modules/some-ui-lib"; /* scan extra sources */
Auto-detection skips node_modules & .gitignored paths — add @source to include a component library's markup, or @source not to exclude.

12v3 → v4 migrationwhat changed

npx @tailwindcss/upgrade★
The official codemod handles most of the move: swaps directives for @import, ports tailwind.config.js into @theme, and updates renamed classes. Run it on a clean git branch.
/* v3 */ @tailwind base; @tailwind components; @tailwind utilities; /* v4 */ @import "tailwindcss";★
The three directives collapse into one import — the clearest signal of which version a codebase is on.
# renamed: shadow-sm→shadow-xs, shadow→shadow-sm, rounded→rounded-sm, outline-none→outline-hidden
Several default-scale names shifted by one step in v4. Also bg-opacity-*/text-opacity-* are gone — use the /NN slash syntax.
# v4 needs modern browsers — no IE/old-Safari; check your support matrix firstgotcha
v4 relies on modern CSS (cascade layers, @property, color-mix). If you must support older browsers, stay on v3.4.

Tailwind CSS cheat sheet

Outline

Setup & core

Utilities & variants

Customization

Setup & Core

Utilities & Variants

Customization & Reference

Worth memorizing