Tailwind CSS v4
Tailwind CSS is a utility-first CSS framework. v4 is a ground-up rewrite: configuration is CSS-first (@theme replaces tailwind.config.js), all colors use OKLCH, and the Vite plugin replaces PostCSS.
Install (v4)
npm install tailwindcss @tailwindcss/vite
/* app.css */
@import "tailwindcss";
// vite.config.ts
import tailwindcss from '@tailwindcss/vite'
export default { plugins: [tailwindcss()] }
Core Concept: Utility-First
Style elements by combining small, single-purpose classes directly in markup. No custom class names, no context switching.
<div class="mx-auto flex max-w-sm items-center gap-4 rounded-xl bg-white p-6 shadow-lg">
<img class="size-12 shrink-0 rounded-full" src="..." />
<div>
<p class="text-xl font-semibold text-gray-900">Title</p>
<p class="text-sm text-gray-500">Subtitle</p>
</div>
</div>
Variant Syntax
Variants prefix any utility: {variant}:{utility}
hover:bg-blue-600 focus:ring-2 active:scale-95
dark:bg-gray-900 sm:flex-row lg:grid-cols-3
disabled:opacity-50 group-hover:text-white peer-invalid:visible
aria-checked:bg-sky-700 data-active:border-2 md:max-lg:hidden
Variants stack: dark:md:hover:bg-fuchsia-600
@theme — Design Tokens
Replace tailwind.config.js with CSS variables:
@import "tailwindcss";
@theme {
--color-brand-500: oklch(0.65 0.2 240);
--font-display: "Inter", sans-serif;
--radius-card: 0.75rem;
--breakpoint-xs: 30rem;
--animate-fade-in: fade-in 0.3s ease-out;
}
Generates: bg-brand-500, font-display, rounded-card, xs:*, animate-fade-in
Key Directives
| Directive | Purpose |
|---|---|
@theme { } | Define design tokens → generates utility classes |
@layer base/components/utilities { } | Add custom CSS to cascade layers |
@utility name { } | Add custom utility (works with all variants) |
@custom-variant name (...) ; | Add reusable custom variant |
@apply util1 util2; | Inline utilities into custom CSS |
@source "../path" | Explicitly add source files for class detection |
@reference "app.css"; | Import theme vars without duplicating CSS |
Arbitrary Values
bg-[#1da1f2] text-[22px] grid-cols-[1fr_500px_2fr]
top-[117px] w-[calc(100%-2rem)] fill-(--brand-color)
Responsive Breakpoints (mobile-first)
| Prefix | Min-width |
|---|---|
sm: | 40rem (640px) |
md: | 48rem (768px) |
lg: | 64rem (1024px) |
xl: | 80rem (1280px) |
2xl: | 96rem (1536px) |
<!-- Stack on mobile, row on md+ -->
<div class="flex flex-col md:flex-row">
Common Patterns
// cn() helper — combine + deduplicate classes
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'
export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) }
<!-- Dark mode -->
<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
<!-- Group: style children based on parent state -->
<a class="group"><span class="text-gray-500 group-hover:text-white">Link</span></a>
<!-- Peer: style siblings based on sibling state -->
<input class="peer" /><p class="hidden peer-invalid:block text-red-500">Invalid</p>
References
- Utility Classes — core concepts, arbitrary values, important modifier
- States & Variants — hover, focus, group, peer, ARIA, data, dark
- Responsive Design — breakpoints, mobile-first, container queries
- Theme & Design Tokens — @theme, namespaces, CSS variables, customization
- Colors — palette, OKLCH, opacity modifiers, dark mode
- Custom Styles — @layer, @apply, @utility, @custom-variant
- Directives & Functions — complete directive/function reference
- shadcn/ui — installation, Tailwind v4 setup, theming, components