Tailwind CSS v4

Write modern, maintainable styles using Tailwind CSS v4’s utility-first approach.

Quick Reference

Responsive: sm:, md:, lg:, xl:, 2xl: (mobile-first) States: hover:, focus:, active:, disabled:, group-hover:, peer-checked: Dark mode: dark: Arbitrary values: top-[117px], bg-[#bada55] CSS variables: bg-(--my-color) (v4 syntax)

Core Concepts

• Utility-First: Compose styles from single-purpose classes directly in HTML
• Mobile-First: Breakpoint prefixes apply at that width and above
• State Variants: Prefix utilities to apply conditionally
• Theme Variables: Define in @theme { } as CSS custom properties

v4 Architecture

CSS-First Configuration

Configuration moved from JS to CSS via @theme:

/* app.css */
@import "tailwindcss";

@theme {
  --font-sans: "Inter", system-ui, sans-serif;
  --color-brand-500: oklch(0.637 0.237 25.331);
  --breakpoint-lg: 64rem;
  --spacing: 0.25rem;
}

Theme values generate both utility classes (bg-brand-500) and CSS variables (var(--color-brand-500)).

Simplified Imports

Replace v3 directives with single import:

/* v3 (deprecated) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

Browser Requirements

Requires: Safari 16.4+, Chrome 111+, Firefox 128+

Uses native CSS features: @property, color-mix(), cascade layers. Use v3.4 for older browsers.

Build Tool Packages

• CLI: @tailwindcss/cli
• PostCSS: @tailwindcss/postcss
• Vite (recommended): @tailwindcss/vite

No longer need postcss-import or autoprefixer as separate dependencies.

v3 to v4 Migration

Run npx @tailwindcss/upgrade for automated migration.

Renamed Utilities

Removed Utilities

• Opacity utilities (bg-opacity-50) → slash syntax (bg-black/50)
• flex-shrink-* → shrink-*
• flex-grow-* → grow-*
• overflow-ellipsis → text-ellipsis

Default Value Changes

• Border color: currentColor (was gray-200)
• Ring color: currentColor (was blue-500)
• Ring width: 1px (was 3px, use ring-3 for old default)
• Placeholder: 50% opacity text color (was gray-400)
• Button cursor: default (was pointer)

Syntax Changes

• CSS variable shorthand: bg-(--my-color) instead of bg-[--my-color]
• Prefix syntax: tw:bg-red-500 (variant-like)
• Variant stacking: Left-to-right order (was right-to-left)
• Hover on mobile: Only applies when device supports hover (@media (hover: hover))

Custom Utilities

Use @utility instead of @layer utilities:

@utility btn-primary {
  background-color: var(--color-brand-500);
  padding: 0.5rem 1rem;
  border-radius: 0.25rem;
}

Scoped Styles (Vue/Svelte/CSS Modules)

Use @reference to access theme in isolated style blocks:

<style scoped>
@reference "../app.css";

.custom { @apply bg-brand-500; }
</style>

Or use CSS variables directly: var(--color-brand-500)

Functions & Directives

Functions:

• --alpha(color / opacity) – adjust color opacity
• --spacing(value) – generate spacing values
• var(--theme-variable) – reference theme variables

Advanced Variants

ARIA: aria-checked:, aria-disabled: Data attributes: data-[size=large]:, data-active: Has selector: has-[:focus]: Child/descendant: *:p-2, **:rounded-full Named groups: group/item, peer-checked/opt1:

Container Queries

<div class="@container">
  <div class="@sm:grid-cols-2 @lg:grid-cols-4">
    <!-- Styles based on container width -->
  </div>
</div>

Named containers: @container/sidebar, @lg/sidebar:

Reference Documentation

Read these files only when you need detailed utility reference:

• Layout – display, position, visibility, columns, overflow
• Flexbox & Grid – flex, grid, alignment, gap
• Spacing & Sizing – padding, margin, width, height
• Typography – fonts, text styling, lists
• Backgrounds & Borders – bg, border, radius, ring
• Effects – shadows, opacity, filters, blend modes
• Transforms & Transitions – scale, rotate, animate
• Interactivity – cursor, scroll, form controls
• SVG & Masks – fill, stroke, mask utilities
• Tables – table layout and borders
• Colors – palette, opacity, customization

Common Patterns

Centering

<!-- Flex -->
<div class="flex items-center justify-center">

<!-- Grid -->
<div class="grid place-items-center">

<!-- Absolute positioning -->
<div class="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2">

Responsive Grid

<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">

Card with Shadow

<div class="rounded-lg bg-white p-6 shadow-md dark:bg-gray-800">

Button

<button class="rounded-md bg-blue-600 px-4 py-2 text-white hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">

Form Input

<input class="w-full rounded-md border border-gray-300 px-3 py-2 focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500">

Truncate Text

<p class="truncate">Very long text...</p>
<!-- or multi-line -->
<p class="line-clamp-3">...</p>