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: npm i @tailwindcss/postcss · webpack plugin since v4.2 · CLI: npx @tailwindcss/cli -i in.css -o out.css --watch
Not on Vite? Use the PostCSS plugin (@tailwindcss/postcss), the webpack plugin (added in v4.2), or the standalone CLI. Same @import in all.
<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 — 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. free. Namespaces: --color-*, --font-*, --spacing-*, --breakpoint-*, --radius-*, …
.hero { background: var(--color-brand); } /* tokens are real CSS vars */
Every theme value is 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 */ · ps-4 me-2 /* logical */
space-x/y-* gaps siblings without touching parent padding. Logical properties (ps/pe/ms/me, start/end) expanded in v4.3 for RTL-aware layouts.
/* 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). v4.2 added mauve, olive, mist & taupe to the default theme.
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.
wrap-break-word wrap-anywhere /* overflow-wrap, v4.1 */
Control how long words break: wrap-break-word (break only when needed) and wrap-anywhere (allow mid-word breaks — handy inside flex containers). New in v4.1.

6Effects & text-shadowdepth & gradients

rounded-lg border shadow-md ring-2 ring-blue-500 transition★
Borders/effects: rounded-*, border[-*], shadow-*, focus ring-*, and transition/duration-*/ease-*. v4 also adds inset-shadow-* & inset-ring-*.
text-shadow-2xs text-shadow-sm text-shadow-lg text-shadow-sky-300★4.1
Text shadows arrived in v4.1: a scale from text-shadow-2xs to text-shadow-lg, plus text-shadow-<color> and opacity (text-shadow-lg/50).
bg-linear-to-r from-indigo-500 to-pink-500 · bg-radial bg-conic★
Gradients: bg-linear-to-* (renamed from bg-gradient-* in v4), plus bg-radial-* & bg-conic-* with from-/via-/to- color stops.
drop-shadow-lg drop-shadow-cyan-500/50 /* colored drop shadows, v4.1 */
drop-shadow-<color> (SVG/PNG-aware shadows) gained color support in v4.1 — drop-shadow-indigo-500, with opacity.

7Responsive 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.

8State & 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 children.

9Container 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. v4.3 also added container-size utilities.

10More variants & pointersv4.1 additions

pointer-fine:p-2 pointer-coarse:p-4 any-pointer-coarse:block★4.1
Pointer variants: pointer-fine (mouse/trackpad) vs pointer-coarse (touch) — give touch UIs bigger targets. any-pointer-* checks if any device matches.
<input class="user-valid:border-green-500 user-invalid:border-red-500">★4.1
user-valid/user-invalid style a field only after the user interacts — no red borders before they've typed. Cleaner than :valid/:invalid.
justify-center-safe items-center-safe items-baseline-last4.1
Safe alignment switches to start instead of clipping on overflow. items-baseline-last aligns to the last text baseline (great for cards of varying text).
noscript:block inverted-colors:bg-white details-content:mt-2
More v4.1 variants: noscript (JS disabled), inverted-colors (OS invert mode), details-content (a <details> body).

11Masks & scrollbars4.1 & 4.3

mask-b-from-50% mask-b-to-80% /* fade an element's bottom edge */★4.1
Mask utilities (v4.1) fade/clip elements with gradients: directional mask-t/r/b/l-from-*/-to-* with ranges — e.g. a soft fade-out edge, no image needed.
mask-radial-from-transparent mask-radial-from-15% mask-radial-to-black mask-radial-at-right
Radial masks: spotlight/vignette effects composed from utilities. Also mask-conic-* and image masks (mask-[url(...)]).
scrollbar-thin scrollbar-none scrollbar-thumb-gray-400 scrollbar-track-gray-100★4.3
First-party scrollbar styling in v4.3: scrollbar-{auto,thin,none} for width and scrollbar-thumb-*/scrollbar-track-* for color — no plugin.
zoom-in tab-size-4 /* other v4.3 utilities */
v4.3 also added zoom-*, tab-size-*, more logical-property utilities, and better @variant support.

12Arbitrary 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, or safelist with @source inline() (card 14).

13Custom 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 (support improved in v4.3).

14Directives, functions & @sourcethe @-rules

@import "tailwindcss" · @theme · @utility · @variant/@custom-variant · @apply★
The v4 directive set. Plus @source to steer the scanner, and @config to load a legacy JS config.
@source inline("underline {hover:,}bg-red-{50,{100..900..100},950}");★4.1
Safelisting: @source inline(...) force-includes classes not found in your source (dynamic class names, CMS content) — with brace expansion. @source not inline("container") excludes.
@source "../node_modules/some-ui-lib"; · @source not "./legacy";
Auto-detection skips node_modules & .gitignored paths — add @source to include a library's markup, or @source not to ignore a path.
margin: --spacing(4); color: theme(--color-brand); /* or var(--color-brand) */
Functions: --spacing() returns a scale value in hand-written CSS; theme() reads a config value (in v4 you can usually just use the CSS variable directly, since tokens are variables).

15What's new (4.1–4.3)since v4.0

# v4.1 — text-shadow-* · mask-* · wrap-* · drop-shadow color · safe align★4.1
Plus the variants pointer-fine/coarse, user-valid/invalid, noscript, inverted-colors, details-content, and @source inline() safelisting.
# v4.2 — new theme colors (mauve, olive, mist, taupe) + webpack plugin4.2
Four new default palettes and official webpack support (@tailwindcss/webpack), alongside fixes.
# v4.3 — scrollbar-* · container-size · more logical props · zoom · tab-size★4.3
First-party scrollbar styling, container-size utilities, expanded logical properties (RTL-aware), and better @variant. Latest is v4.3.3 (2026-07-16).
# upgrade within v4: bump the package; no config migration needed
These are additive minor releases — moving 4.0→4.3 is a dependency bump. (The big change is still v3→v4; see card 16.)

16v3 → 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 · rounded→rounded-sm · outline-none→outline-hidden · bg-gradient-*→bg-linear-*
Several default-scale & gradient names shifted 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

Variants & queries

Customize & reference

Setup & Core

Core Utilities

Variants & Queries

Customization

Reference & Migration

Worth memorizing