Tailwind Reference

This section documents Tailwind CSS v4.x — the CSS-first configuration line, whose v4.0 release shipped in January 2025 — as published at the official Tailwind CSS documentation, which is the reference these pages are written and verified against. No specific patch version is pinned.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production, since Tailwind iterates quickly.

This section’s bibliography lists the reference material consulted while preparing these pages.

Welcome to the Tailwind CSS reference. Tailwind CSS is a utility-first CSS framework: instead of shipping pre-designed components, it gives you thousands of small single-purpose classes (flex, pt-4, text-lg, bg-sky-500/75, md:grid-cols-3, hover:underline, dark:bg-gray-900) that you compose directly in your markup, plus variants for states, breakpoints, dark mode, container queries and attribute selectors, a design-token theme you configure in CSS, and a build step that scans your source and generates only the CSS you used. This section documents the current Tailwind CSS v4.x line (v4.0 shipped January 2025), which replaced the JavaScript tailwind.config.js with a CSS-first configuration (@import "tailwindcss"; + @theme { }), written and verified against https://tailwindcss.com/docs/.

If you are new to Tailwind, read Getting Started with Tailwind CSS and Utility-First Fundamentals first, then Hover, Focus, and Other States and Responsive Design. If you are coming from Tailwind 3, start with Upgrading from v3 to v4.

What’s covered

Getting started

  • Getting Started with Tailwind CSS — utility-first vs. component frameworks, the install paths (Vite, PostCSS, CLI and standalone binary, framework guides, Play CDN), the one-line @import "tailwindcss" stylesheet, editor setup, and the browser-support baseline.

Core concepts

  • Utility-First Fundamentals — what a utility class is, why not inline styles, managing duplication with loops and components (and why not @apply), and the state-to-variant mental model.

  • Hover, Focus, and Other States — pseudo-class and pseudo-element variants, group- / peer-, the / * child variants, has- / not- / in-, aria- / data-* attribute variants, media and feature variants, left-to-right stacking, and @custom-variant.

  • Responsive Design — the mobile-first breakpoint system, max- ranges, arbitrary breakpoints, customizing --breakpoint-, and built-in container queries.

  • Dark Mode — the dark: variant, the prefers-color-scheme default, the class and data-attribute strategies via @custom-variant, and a three-state JS toggle.

  • Theme Variables and Colors — @theme, the theme-variable namespaces, extending vs. overriding vs. clearing, the OKLCH palette, and the / opacity modifier.

Base styles

  • Preflight and Base Styles — what Preflight resets, how it ships with @import "tailwindcss", extending it with @layer base, and disabling it.

Utility families

  • Layout — display, box-sizing, position and inset, overflow, aspect-ratio, columns, container, and the table utilities.

  • Flexbox and Grid — flex containers and items, grid templates and placement, gap-*, and box alignment.

  • Spacing and Sizing — padding, margin and negative margins, space-, the --spacing scale, and width/height/size- with the --container-* scale.

  • Typography — font family/size/weight/style, spacing and wrapping, colour and decoration, lists, and the official Typography and Forms plugins.

  • Backgrounds, Borders, and Effects — backgrounds and gradients, borders/divide/outline/ring (with the v4 default-colour changes), and box/text shadows, opacity, blend modes, and masks.

  • Filters, Transitions, and Transforms — filter and backdrop-filter, transitions and timing, built-in and custom animations, and 2D/3D transforms.

  • Interactivity, SVG, and Accessibility — accent/caret colour, appearance, cursor, field-sizing, scroll behaviour and snap, fill/stroke, and sr-only / forced-color-adjust.

Customization

  • Customization and Configuration — the CSS-first model, automatic class detection and safelisting with @source, @plugin, the legacy @config, the prefix option, the cascade layers, and the --spacing() / --alpha() functions.

  • Custom Styles and Arbitrary Values — arbitrary values, properties and variants, the (--var) shorthand, data-type hints, @utility (including functional utilities), @custom-variant, @variant, and @apply / @reference.

Build and upgrade

  • Build and Production — how the scan/build works, why there is no purge step in v4, minification, the three integration shapes, and a CI note.

  • Upgrading from v3 to v4 — the automated tool, CSS-first configuration, renamed and removed utilities, changed defaults, the raised browser baseline, and how to read v3-era material against v4.

Putting it together

  • Building a Page with Utilities — a responsive header, hero, and card grid built with utilities, then layered with responsive variants, states, dark mode, a component, and one @theme customization.

Reference

  • Cheat sheet — a one-page, downloadable PDF summary of the essentials above for quick memorization.

Bibliography