Tailwind CSS v4 Fundamentals (2025/2026)

Overview

Tailwind CSS v4.0 was released January 22, 2025, featuring a complete rewrite with a Rust-based engine, CSS-first configuration, and significant performance improvements.

Key Changes from v3

Installation

Vite Projects (Recommended)

npm install -D tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [tailwindcss()]
})

PostCSS Projects

npm install -D tailwindcss @tailwindcss/postcss

// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

CSS Entry Point

/* app.css - The only required CSS file */
@import "tailwindcss";

CSS-First Configuration

The @theme Directive

Replace tailwind.config.js with CSS-based configuration:

@import "tailwindcss";

@theme {
  /* Colors using modern oklch */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  --color-accent: oklch(0.8 0.2 30);

  /* Typography */
  --font-display: "Satoshi", sans-serif;
  --font-body: "Inter", sans-serif;

  /* Custom spacing */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  --spacing-xl: 4rem;

  /* Custom breakpoints */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

Theme Variables Reference

Disabling Defaults

@theme {
  /* Start fresh - disable all default theme values */
  --*: initial;

  /* Define only what you need */
  --spacing: 4px;
  --font-body: Inter, sans-serif;
  --color-primary: oklch(0.72 0.11 221.19);
  --color-secondary: oklch(0.74 0.17 40.24);
}

Custom Utilities

Static Utilities

/* Define custom utility in CSS */
@utility content-auto {
  content-visibility: auto;
}

@utility text-balance {
  text-wrap: balance;
}

@utility scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
}

@utility scrollbar-hide::-webkit-scrollbar {
  display: none;
}

Usage:

<div class="content-auto scrollbar-hide">
  <h1 class="text-balance">Long headline that should balance nicely</h1>
</div>

Functional Utilities

/* Utility that accepts values */
@utility tab-* {
  tab-size: --value(integer);
}

@utility text-shadow-* {
  text-shadow: 0 0 --value([length]) currentColor;
}

/* With theme reference */
@utility gap-safe-* {
  gap: max(--value(--spacing-*), env(safe-area-inset-bottom));
}

Usage:

<pre class="tab-4">Code with 4-space tabs</pre>
<h1 class="text-shadow-[2px]">Glowing text</h1>
<div class="gap-safe-4">Safe area aware gap</div>

Custom Variants

The @custom-variant Directive

/* Dark mode with selector */
@custom-variant dark (&:where(.dark, .dark *));

/* Custom state variants */
@custom-variant hocus (&:hover, &:focus);
@custom-variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);

/* Data attribute variants */
@custom-variant data-loading (&[data-loading="true"]);
@custom-variant data-active (&[data-state="active"]);

/* Child selectors */
@custom-variant children (& > *);
@custom-variant not-first (& > *:not(:first-child));

Usage:

<button class="hocus:bg-blue-600">Hover or focus</button>
<div class