Skip to main content

TailwindCSS Cheatsheet

Complete reference guide for Tailwind CSS v4 utility classes, CSS-first configuration, and modern CSS features for rapid UI development

Table of Contents


Installation & Setup

Prerequisites πŸ“‹

  • Node.js 20+ (required for upgrade tool)
  • Modern browsers: Safari 16.4+, Chrome 111+, Firefox 128+
  • Modern build tool (Vite, Next.js, Astro, etc.)

Installation Methods πŸ”§

Terminal window
# Using npm
npm install tailwindcss @tailwindcss/postcss
# Using pnpm (recommended)
pnpm add tailwindcss @tailwindcss/postcss
# Using yarn
yarn add tailwindcss @tailwindcss/postcss

PostCSS Configuration πŸ“

// postcss.config.js or postcss.config.mjs
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};

CSS Import (v4 Style) 🎨

/* src/styles/global.css or input.css */
/* Single import replaces @tailwind directives */
@import "tailwindcss";
vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
plugins: [
tailwindcss(), // Better performance than PostCSS
],
});

Framework Integration 🌐

/* Next.js, Astro, Vite - All use the same CSS import */
@import "tailwindcss";
/* Optional: Add custom source paths */
@source "../node_modules/@my-company/ui-lib";

Automatic Content Detection πŸ”

Tailwind CSS v4 automatically detects template files:

  • Scans all files in your project
  • Ignores .gitignore entries automatically
  • Ignores binary files (images, videos, etc.)
  • No content array configuration needed!
/* Explicitly add sources if needed */
@import "tailwindcss";
@source "../shared-components";

Core Concepts

Utility-First Philosophy 🎯

<!-- Traditional CSS approach -->
<div class="card">Card content</div>
<style>
.card {
padding: 1rem;
background: white;
border-radius: 0.5rem;
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}
</style>
<!-- Tailwind utility approach -->
<div class="p-4 bg-white rounded-lg shadow-sm">Card content</div>

Class Combination πŸ“¦

<!-- Multiple utilities combine -->
<div
class="flex items-center justify-between p-4 bg-blue-500 text-white rounded-lg"
>
Combined utilities
</div>
<!-- Responsive + state variants -->
<button
class="px-4 py-2 bg-blue-500 hover:bg-blue-600 active:scale-95 transition-all"
>
Interactive button
</button>

Dynamic Utility Values 🎲

<!-- Dynamic spacing - no arbitrary syntax needed! -->
<div class="mt-17 pr-29 w-42">Dynamic spacing values work out of the box</div>
<!-- Dynamic grid columns -->
<div class="grid grid-cols-15">Any number of columns without configuration</div>
<!-- Custom values using square brackets -->
<div class="w-[500px] h-[300px] bg-[#1da1f2]">Custom dimensions and colors</div>
<!-- CSS variables in arbitrary values (v4 syntax) -->
<div class="bg-(--brand-color)">Use parentheses for CSS variables</div>

CSS Variables Access 🎨

/* All theme values available as CSS variables */
:root {
--color-blue-500: oklch(0.623 0.214 259.815);
--spacing: 0.25rem;
--breakpoint-lg: 64rem;
/* ... all theme values */
}
<!-- Use CSS variables directly -->
<div style="background-color: var(--color-blue-500)">
Direct CSS variable access
</div>

CSS-First Configuration

Theme Configuration with @theme 🎨

/* Configure everything in CSS - no JS config needed! */
@import "tailwindcss";
@theme {
/* Custom fonts */
--font-display: "Satoshi", "sans-serif";
/* Custom breakpoints */
--breakpoint-3xl: 1920px;
--breakpoint-xs: 475px;
/* Custom colors (OKLCH format) */
--color-avocado-100: oklch(0.99 0 0);
--color-avocado-200: oklch(0.98 0.04 113.22);
--color-avocado-300: oklch(0.94 0.11 115.03);
--color-avocado-400: oklch(0.92 0.19 114.08);
--color-avocado-500: oklch(0.84 0.18 117.33);
--color-avocado-600: oklch(0.53 0.12 118.34);
/* Custom spacing */
--spacing-128: 32rem;
--spacing-144: 36rem;
/* Custom easing functions */
--ease-fluid: cubic-bezier(0.3, 0, 0, 1);
--ease-snappy: cubic-bezier(0.2, 0, 0, 1);
/* Custom shadows */
--shadow-custom: 0 10px 25px -5px rgba(0, 0, 0, 0.1);
}

Custom Utilities with @utility πŸ› οΈ

/* Register custom utilities */
@utility btn {
border-radius: 0.5rem;
padding: 0.5rem 1rem;
background-color: ButtonFace;
}
@utility scrollbar-hide {
-ms-overflow-style: none;
scrollbar-width: none;
&::-webkit-scrollbar {
display: none;
}
}
/* Custom utilities work with all variants */
.btn:hover {
/* Automatically works! */
}

Custom Variants 🎭

/* Define custom variants */
@custom-variant hover-touch (&:hover);
/* Use in HTML */
<div class="hover-touch:bg-blue-500">
Custom variant
</div>

Utility Classes

Display & Positioning πŸ“

<!-- Display types -->
<div class="block">Block element</div>
<div class="inline">Inline element</div>
<div class="inline-block">Inline block</div>
<div class="flex">Flex container</div>
<div class="grid">Grid container</div>
<div class="hidden">Hidden element</div>
<!-- Position -->
<div class="static">Static (default)</div>
<div class="relative">Relative positioning</div>
<div class="absolute">Absolute positioning</div>
<div class="fixed">Fixed positioning</div>
<div class="sticky">Sticky positioning</div>
<!-- Z-index -->
<div class="z-0">z-index: 0</div>
<div class="z-10">z-index: 10</div>
<div class="z-50">z-index: 50</div>
<div class="z-auto">z-index: auto</div>

Overflow Handling πŸ’§

<!-- Overflow -->
<div class="overflow-auto">Scroll when needed</div>
<div class="overflow-hidden">Hide overflow</div>
<div class="overflow-visible">Show overflow</div>
<div class="overflow-scroll">Always scroll</div>
<!-- Direction-specific -->
<div class="overflow-x-auto overflow-y-hidden">Horizontal scroll only</div>

Layout & Spacing

Flexbox Layout πŸ”„

<!-- Flex direction -->
<div class="flex flex-row">Row (default)</div>
<div class="flex flex-row-reverse">Row reversed</div>
<div class="flex flex-col">Column</div>
<div class="flex flex-col-reverse">Column reversed</div>
<!-- Flex wrap -->
<div class="flex flex-wrap">Wrap items</div>
<div class="flex flex-nowrap">No wrap (default)</div>
<div class="flex flex-wrap-reverse">Wrap reversed</div>
<!-- Alignment -->
<div class="flex items-start">Align items start</div>
<div class="flex items-center">Align items center</div>
<div class="flex items-end">Align items end</div>
<div class="flex items-stretch">Align items stretch</div>
<!-- Justify content -->
<div class="flex justify-start">Justify start</div>
<div class="flex justify-center">Justify center</div>
<div class="flex justify-end">Justify end</div>
<div class="flex justify-between">Space between</div>
<div class="flex justify-around">Space around</div>
<div class="flex justify-evenly">Space evenly</div>
<!-- Flex grow/shrink -->
<div class="flex-1">Grow to fill space</div>
<div class="flex-auto">Flex: auto</div>
<div class="flex-none">Don't flex</div>
<div class="grow">Grow if needed</div>
<div class="shrink">Shrink if needed</div>

Grid Layout πŸ“

<!-- Grid columns (dynamic values work!) -->
<div class="grid grid-cols-1">1 column</div>
<div class="grid grid-cols-2">2 columns</div>
<div class="grid grid-cols-3">3 columns</div>
<div class="grid grid-cols-15">15 columns (no config needed!)</div>
<div class="grid grid-cols-[200px_1fr_300px]">Custom columns</div>
<!-- Grid rows -->
<div class="grid grid-rows-3">3 rows</div>
<div class="grid grid-rows-[auto_1fr_auto]">Custom rows</div>
<!-- Gap -->
<div class="grid gap-4">Gap 1rem</div>
<div class="grid gap-x-4 gap-y-2">Different x/y gaps</div>
<div class="grid gap-0">No gap</div>
<!-- Grid placement -->
<div class="col-span-2">Span 2 columns</div>
<div class="col-start-2 col-end-4">Start col 2, end col 4</div>
<div class="row-span-2">Span 2 rows</div>

Spacing Utilities πŸ“

<!-- Padding (dynamic values work!) -->
<div class="p-0">padding: 0</div>
<div class="p-1">padding: 0.25rem</div>
<div class="p-2">padding: 0.5rem</div>
<div class="p-4">padding: 1rem</div>
<div class="p-8">padding: 2rem</div>
<div class="p-17">Dynamic padding (no config!)</div>
<div class="px-4">Horizontal padding</div>
<div class="py-4">Vertical padding</div>
<div class="pt-4 pb-2 pl-3 pr-5">Individual sides</div>
<!-- Margin -->
<div class="m-0">margin: 0</div>
<div class="m-4">margin: 1rem</div>
<div class="mx-auto">Horizontal center</div>
<div class="my-4">Vertical margin</div>
<div class="mt-4 mb-2 ml-3 mr-5">Individual sides</div>
<div class="-m-4">Negative margin</div>
<!-- Space between -->
<div class="space-y-4">Vertical space between children</div>
<div class="space-x-4">Horizontal space between children</div>

Width & Height πŸ“

<!-- Width (dynamic values work!) -->
<div class="w-0">width: 0</div>
<div class="w-auto">width: auto</div>
<div class="w-full">width: 100%</div>
<div class="w-screen">width: 100vw</div>
<div class="w-1/2">width: 50%</div>
<div class="w-1/3">width: 33.333%</div>
<div class="w-1/4">width: 25%</div>
<div class="w-[500px]">Custom width</div>
<div class="w-42">Dynamic width (no config!)</div>
<div class="min-w-0">min-width: 0</div>
<div class="max-w-xs">max-width: 20rem</div>
<div class="max-w-screen-lg">max-width: 1024px</div>
<!-- Height -->
<div class="h-0">height: 0</div>
<div class="h-auto">height: auto</div>
<div class="h-full">height: 100%</div>
<div class="h-screen">height: 100vh</div>
<div class="h-[500px]">Custom height</div>
<div class="min-h-screen">min-height: 100vh</div>
<div class="max-h-96">max-height: 24rem</div>

Typography

Font Family πŸ”€

<!-- Font families -->
<p class="font-sans">Sans-serif (default)</p>
<p class="font-serif">Serif</p>
<p class="font-mono">Monospace</p>
<!-- Custom font -->
<p class="font-['Inter']">Custom font</p>

Font Size & Weight πŸ“

<!-- Font sizes -->
<p class="text-xs">Extra small (0.75rem)</p>
<p class="text-sm">Small (0.875rem)</p>
<p class="text-base">Base (1rem)</p>
<p class="text-lg">Large (1.125rem)</p>
<p class="text-xl">Extra large (1.25rem)</p>
<p class="text-2xl">2xl (1.5rem)</p>
<p class="text-3xl">3xl (1.875rem)</p>
<p class="text-4xl">4xl (2.25rem)</p>
<p class="text-5xl">5xl (3rem)</p>
<p class="text-6xl">6xl (3.75rem)</p>
<p class="text-7xl">7xl (4.5rem)</p>
<p class="text-8xl">8xl (6rem)</p>
<p class="text-9xl">9xl (8rem)</p>
<!-- Font weights -->
<p class="font-thin">100</p>
<p class="font-extralight">200</p>
<p class="font-light">300</p>
<p class="font-normal">400</p>
<p class="font-medium">500</p>
<p class="font-semibold">600</p>
<p class="font-bold">700</p>
<p class="font-extrabold">800</p>
<p class="font-black">900</p>

Text Styling ✏️

<!-- Text alignment -->
<p class="text-left">Left aligned</p>
<p class="text-center">Center aligned</p>
<p class="text-right">Right aligned</p>
<p class="text-justify">Justified</p>
<!-- Text decoration -->
<p class="underline">Underline</p>
<p class="overline">Overline</p>
<p class="line-through">Strikethrough</p>
<p class="no-underline">No decoration</p>
<!-- Text transform -->
<p class="uppercase">UPPERCASE</p>
<p class="lowercase">lowercase</p>
<p class="capitalize">Capitalize Words</p>
<p class="normal-case">Normal Case</p>
<!-- Letter & line spacing -->
<p class="tracking-tight">Tight letter spacing</p>
<p class="tracking-normal">Normal letter spacing</p>
<p class="tracking-wide">Wide letter spacing</p>
<p class="leading-none">Line height: 1</p>
<p class="leading-tight">Line height: 1.25</p>
<p class="leading-normal">Line height: 1.5</p>
<p class="leading-relaxed">Line height: 1.625</p>
<p class="leading-loose">Line height: 2</p>
<!-- Text overflow -->
<p class="truncate">Truncate with ellipsis</p>
<p class="text-ellipsis overflow-hidden">Custom truncation</p>
<p class="break-words">Break long words</p>
<p class="break-all">Break all</p>

Colors & Backgrounds

Color Palette (OKLCH) 🎨

<!-- Text colors (OKLCH color model in v4) -->
<p class="text-black">Black text</p>
<p class="text-white">White text</p>
<p class="text-gray-500">Gray text</p>
<p class="text-red-500">Red text</p>
<p class="text-blue-500">Blue text</p>
<p class="text-green-500">Green text</p>
<p class="text-yellow-500">Yellow text</p>
<p class="text-purple-500">Purple text</p>
<p class="text-pink-500">Pink text</p>
<p class="text-indigo-500">Indigo text</p>
<p class="text-cyan-500">Cyan text</p>
<p class="text-orange-500">Orange text</p>
<!-- Background colors -->
<div class="bg-white">White background</div>
<div class="bg-black">Black background</div>
<div class="bg-gray-100">Light gray</div>
<div class="bg-gray-900">Dark gray</div>
<div class="bg-blue-500">Blue background</div>
<div class="bg-red-500">Red background</div>
<div class="bg-green-500">Green background</div>
<div class="bg-transparent">Transparent</div>
<div class="bg-[#1da1f2]">Custom color</div>
<!-- Color opacity (using color-mix) -->
<div class="bg-blue-500/50">50% opacity</div>
<div class="bg-blue-500/75">75% opacity</div>
<div class="text-gray-500/50">Text with opacity</div>

Gradient Backgrounds 🌈

<!-- Linear gradients (renamed from bg-gradient-*) -->
<div class="bg-linear-to-r from-blue-500 to-purple-500">Left to right</div>
<div class="bg-linear-to-l from-blue-500 to-purple-500">Right to left</div>
<div class="bg-linear-to-t from-blue-500 to-purple-500">Bottom to top</div>
<div class="bg-linear-to-b from-blue-500 to-purple-500">Top to bottom</div>
<div class="bg-linear-45 from-blue-500 to-purple-500">
Custom angle (45 degrees)
</div>
<!-- Multiple color stops -->
<div class="bg-linear-to-r from-blue-500 via-purple-500 to-pink-500">
Three color gradient
</div>
<!-- Gradient interpolation modes -->
<div class="bg-linear-to-r/srgb from-indigo-500 to-teal-400">
sRGB interpolation
</div>
<div class="bg-linear-to-r/oklch from-indigo-500 to-teal-400">
OKLCH interpolation (more vivid)
</div>
<!-- Radial gradients (NEW in v4) -->
<div class="bg-radial-[at_25%_25%] from-white to-zinc-900 to-75%">
Radial gradient
</div>
<!-- Conic gradients (NEW in v4) -->
<div class="bg-conic/[in_hsl_longer_hue] from-red-600 to-red-600">
Conic gradient
</div>

Borders & Effects

Borders πŸ”²

<!-- Border width -->
<div class="border">1px border</div>
<div class="border-0">No border</div>
<div class="border-2">2px border</div>
<div class="border-4">4px border</div>
<div class="border-8">8px border</div>
<div class="border-t-2">Top border only</div>
<div class="border-r-2">Right border only</div>
<div class="border-b-2">Bottom border only</div>
<div class="border-l-2">Left border only</div>
<!-- Border color (default is currentColor in v4) -->
<div class="border border-gray-300">Gray border</div>
<div class="border border-blue-500">Blue border</div>
<div class="border border-red-500">Red border</div>
<!-- Border radius (renamed scale) -->
<div class="rounded-none">No radius</div>
<div class="rounded-xs">Extra small (was rounded-sm)</div>
<div class="rounded-sm">Small (was rounded)</div>
<div class="rounded-md">Medium radius</div>
<div class="rounded-lg">Large radius</div>
<div class="rounded-xl">Extra large radius</div>
<div class="rounded-2xl">2xl radius</div>
<div class="rounded-full">Full circle</div>
<div class="rounded-t-lg">Top corners only</div>
<div class="rounded-b-lg">Bottom corners only</div>
<div class="rounded-l-lg">Left corners only</div>
<div class="rounded-r-lg">Right corners only</div>

Shadows & Effects ✨

<!-- Box shadows (renamed scale) -->
<div class="shadow-xs">Extra small (was shadow-sm)</div>
<div class="shadow-sm">Small (was shadow)</div>
<div class="shadow-md">Medium shadow</div>
<div class="shadow-lg">Large shadow</div>
<div class="shadow-xl">Extra large shadow</div>
<div class="shadow-2xl">2xl shadow</div>
<div class="shadow-inner">Inner shadow</div>
<div class="shadow-none">No shadow</div>
<!-- Inset shadows (NEW in v4) -->
<div class="inset-shadow-xs">Inset shadow</div>
<div class="inset-shadow-sm">Inset shadow medium</div>
<div class="inset-ring-2">Inset ring</div>
<!-- Opacity -->
<div class="opacity-0">Fully transparent</div>
<div class="opacity-25">25% opacity</div>
<div class="opacity-50">50% opacity</div>
<div class="opacity-75">75% opacity</div>
<div class="opacity-100">Fully opaque</div>
<!-- Backdrop blur (renamed scale) -->
<div class="backdrop-blur-xs">Extra small (was backdrop-blur-sm)</div>
<div class="backdrop-blur-sm">Small (was backdrop-blur)</div>
<div class="backdrop-blur-md">Medium blur</div>
<div class="backdrop-blur-lg">Large blur</div>
<div class="backdrop-blur-xl">Extra large blur</div>
<div class="backdrop-blur-2xl">2xl blur</div>
<div class="backdrop-blur-none">No blur</div>

Responsive Design

Breakpoints πŸ“±

<!-- Default breakpoints -->
<!-- sm: 640px, md: 768px, lg: 1024px, xl: 1280px, 2xl: 1536px -->
<!-- Mobile first approach -->
<div class="w-full md:w-1/2 lg:w-1/3 xl:w-1/4">Responsive width</div>
<!-- Responsive display -->
<div class="hidden md:block">Hidden on mobile, visible on md+</div>
<div class="block md:hidden">Visible on mobile, hidden on md+</div>
<!-- Responsive flex direction -->
<div class="flex flex-col md:flex-row">Column on mobile, row on desktop</div>
<!-- Responsive padding -->
<div class="p-4 md:p-8 lg:p-12">Increasing padding on larger screens</div>
<!-- Responsive grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
Responsive grid columns
</div>
<!-- Responsive typography -->
<h1 class="text-2xl md:text-4xl lg:text-6xl">Responsive heading</h1>

Container Queries πŸ“¦

<!-- Container queries (built-in, no plugin needed!) -->
<div class="@container">
<div class="@sm:grid-cols-2 @lg:grid-cols-4">
Responsive to container size
</div>
</div>
<!-- Max-width container queries (NEW in v4) -->
<div class="@container">
<div class="grid grid-cols-3 @max-md:grid-cols-1">
Max-width container query
</div>
</div>
<!-- Container query ranges -->
<div class="@container">
<div class="flex @min-md:@max-xl:hidden">
Visible only between md and xl container sizes
</div>
</div>

State Variants

Hover & Focus πŸ–±οΈ

<!-- Hover states (only applies on hover-capable devices in v4) -->
<button class="bg-blue-500 hover:bg-blue-600">
Hover effect
</button>
<div class="opacity-75 hover:opacity-100">
Hover opacity change
</div>
<a class="text-blue-500 hover:text-blue-700 hover:underline">
Hover link
</a>
<!-- Focus states -->
<input class="border-gray-300 focus:border-blue-500 focus:ring-3 focus:ring-blue-500">
Focused input
</input>
<button class="focus:outline-hidden focus:ring-3 focus:ring-blue-500">
Focus ring (outline-hidden replaces outline-none)
</button>
<!-- Active states -->
<button class="bg-blue-500 active:bg-blue-700">
Active state
</button>

Disabled & Other States 🚫

<!-- Disabled state -->
<button class="bg-gray-400 disabled:bg-gray-300 disabled:cursor-not-allowed">
Disabled button
</button>
<input class="disabled:opacity-50 disabled:cursor-not-allowed">
Disabled input
</input>
<!-- Checked state -->
<input type="checkbox" class="checked:bg-blue-500">
Checked checkbox
</input>
<!-- Data attributes (dynamic in v4!) -->
<div data-current class="opacity-75 data-current:opacity-100">
No config needed for custom data attributes
</div>
<!-- Group hover -->
<div class="group">
<div class="group-hover:bg-blue-500">
Hover parent affects child
</div>
</div>
<!-- Peer state -->
<input type="checkbox" class="peer">
<div class="peer-checked:block hidden">
Shown when peer is checked
</div>
<!-- Inert variant (NEW in v4) -->
<div inert class="inert:opacity-50">
Styled when inert attribute is present
</div>

New Variants in v4 πŸ†•

<!-- @starting-style variant (NEW) -->
<div
popover
id="my-popover"
class="transition-discrete starting:open:opacity-0"
>
Animate on first display
</div>
<!-- not-* variant (NEW) -->
<div class="not-hover:opacity-75">Apply when NOT hovered</div>
<div class="not-supports-hanging-punctuation:px-4">
Apply when feature not supported
</div>
<!-- nth-* variants (NEW) -->
<div class="nth-3:bg-blue-500">Style nth child</div>
<!-- in-* variant (implicit groups, NEW) -->
<div class="in-group:bg-blue-500">No need for group class</div>

Customization

Theme Configuration 🎨

/* CSS-first configuration with @theme */
@import "tailwindcss";
@theme {
/* Custom colors (OKLCH format recommended) */
--color-brand-blue: oklch(0.623 0.214 259.815);
--color-brand-purple: oklch(0.623 0.214 259.815);
/* Custom spacing */
--spacing-128: 32rem;
--spacing-144: 36rem;
/* Custom font sizes */
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
/* Custom breakpoints */
--breakpoint-xs: 475px;
--breakpoint-3xl: 1920px;
/* Custom border radius */
--radius-4xl: 2rem;
/* Custom easing */
--ease-fluid: cubic-bezier(0.3, 0, 0, 1);
--ease-snappy: cubic-bezier(0.2, 0, 0, 1);
}

Custom Utilities πŸ› οΈ

/* Register custom utilities with @utility */
@utility scrollbar-hide {
-ms-overflow-style: none;
scrollbar-width: none;
&::-webkit-scrollbar {
display: none;
}
}
@utility text-balance {
text-wrap: balance;
}
/* Custom utilities work with all variants automatically */
.scrollbar-hide:hover {
/* Works! */
}

CSS Variables Integration 🎯

/* All theme values available as CSS variables */
:root {
--color-blue-500: oklch(0.623 0.214 259.815);
--spacing: 0.25rem;
--breakpoint-lg: 64rem;
/* ... all theme values */
}
<!-- Use CSS variables directly -->
<div style="background-color: var(--color-blue-500)">
Direct CSS variable access
</div>
<!-- Or in arbitrary values -->
<div class="bg-(--color-blue-500)">CSS variable in arbitrary value</div>

Using JavaScript Config (Legacy) πŸ“

/* Load JS config if needed (not recommended) */
@config "../../tailwind.config.js";
// tailwind.config.js (legacy support)
module.exports = {
// Only theme.extend supported
theme: {
extend: {
colors: {
"brand-blue": "#1e40af",
},
},
},
};

Advanced Features

3D Transforms 🎭

<!-- 3D transform utilities (NEW in v4) -->
<div class="perspective-distant">
<article class="rotate-x-51 rotate-z-43 transform-3d">
3D transformed element
</article>
</div>
<!-- 3D rotation -->
<div class="rotate-x-45">Rotate on X axis</div>
<div class="rotate-y-45">Rotate on Y axis</div>
<div class="rotate-z-45">Rotate on Z axis</div>
<!-- 3D translation -->
<div class="translate-z-10">Translate on Z axis</div>
<!-- 3D scaling -->
<div class="scale-z-2">Scale on Z axis</div>
<!-- Perspective -->
<div class="perspective-1000">Custom perspective</div>
<div class="perspective-distant">Distant perspective</div>

Dark Mode πŸŒ™

<!-- Dark mode classes -->
<div class="bg-white dark:bg-gray-900">Light/dark background</div>
<p class="text-gray-900 dark:text-white">Light/dark text</p>
<!-- Toggle dark mode -->
<script>
document.documentElement.classList.toggle("dark");
</script>

Animation & Transitions 🎬

<!-- Transitions -->
<button class="transition-all duration-300 ease-in-out">
Smooth transition
</button>
<div class="transition-colors duration-200">Color transition only</div>
<!-- Transform (individual properties in v4) -->
<div class="hover:scale-110 hover:rotate-3">Hover transform</div>
<div class="translate-x-4 translate-y-2">Translate</div>
<div class="rotate-45">Rotate</div>
<div class="scale-110">Scale</div>
<!-- Reset transforms -->
<div class="scale-150 focus:scale-none">Reset scale on focus</div>
<!-- Animation -->
<div class="animate-spin">Spinning</div>
<div class="animate-pulse">Pulsing</div>
<div class="animate-bounce">Bouncing</div>
<div class="animate-ping">Pinging</div>

Custom Animations 🎨

/* Define custom animations in @theme */
@theme {
--animate-fade-in: fade-in 0.5s ease-in-out;
--animate-slide-up: slide-up 0.3s ease-out;
@keyframes fade-in {
0% {
opacity: 0;
}
100% {
opacity: 1;
}
}
@keyframes slide-up {
0% {
transform: translateY(20px);
opacity: 0;
}
100% {
transform: translateY(0);
opacity: 1;
}
}
}

Field Sizing (NEW) πŸ“

<!-- Auto-resizing textareas (NEW in v4) -->
<textarea class="field-sizing-content">
Auto-resizes based on content
</textarea>

Color Scheme 🎨

<!-- Control color scheme (NEW in v4) -->
<div class="color-scheme-dark">Dark scrollbars and form controls</div>

Best Practices

Do’s βœ…

  • βœ… Use CSS-first configuration with @theme for customization
  • βœ… Leverage automatic content detection (no config needed!)
  • βœ… Use dynamic utility values (no arbitrary syntax for spacing, grid, etc.)
  • βœ… Access theme values via CSS variables (var(--color-blue-500))
  • βœ… Use Vite plugin for better performance
  • βœ… Leverage container queries for component-level responsiveness
  • βœ… Use OKLCH color format for better color consistency
  • βœ… Extract repeated patterns into @utility directives
  • βœ… Use @starting-style for enter/exit animations
  • βœ… Leverage new gradient APIs (radial, conic, interpolation modes)
  • βœ… Use 3D transforms for advanced effects
  • βœ… Take advantage of built-in import support

Don’ts ❌

  • ❌ Don’t use JavaScript config unless necessary (prefer @theme)
  • ❌ Don’t configure content array (automatic detection works!)
  • ❌ Don’t use arbitrary values when dynamic values work
  • ❌ Don’t use @tailwind directives (use @import "tailwindcss")
  • ❌ Don’t use postcss-import or autoprefixer (built-in!)
  • ❌ Don’t use deprecated utilities (bg-opacity-*, text-opacity-*, etc.)
  • ❌ Don’t forget to update shadow/radius/blur utilities (renamed scale)
  • ❌ Don’t use outline-none (use outline-hidden instead)
  • ❌ Don’t use ring without width (use ring-3 for v3 behavior)
  • ❌ Don’t use Sass/Less/Stylus (Tailwind is the preprocessor)
  • ❌ Don’t forget browser requirements (Safari 16.4+, Chrome 111+, Firefox 128+)

Common Patterns 🎯

<!-- Card component -->
<div
class="bg-white rounded-lg shadow-sm p-6 hover:shadow-md transition-shadow"
>
Card content
</div>
<!-- Button component -->
<button
class="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 active:scale-95 transition-all focus:outline-hidden focus:ring-3 focus:ring-blue-500"
>
Click me
</button>
<!-- Input component -->
<input
class="w-full px-4 py-2 border border-gray-300 rounded-md focus:outline-hidden focus:ring-3 focus:ring-blue-500 focus:border-transparent"
type="text"
/>
<!-- Modal overlay -->
<div
class="fixed inset-0 bg-black/50 backdrop-blur-sm flex items-center justify-center"
>
<div class="bg-white rounded-lg p-6 max-w-md w-full mx-4">Modal content</div>
</div>
<!-- Navigation bar -->
<nav class="bg-white shadow-sm sticky top-0 z-50">
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
<div class="flex justify-between items-center h-16">Navigation content</div>
</div>
</nav>

Performance Tips ⚑

/* Tailwind v4 is optimized by default */
/* Full builds: 5x faster */
/* Incremental builds: 100x+ faster */
/* 75% less memory usage */
/* Use Vite plugin for best performance */
/* Automatic content detection is fast */
/* No need to configure content paths */

Component Extraction πŸ“¦

/* Using @utility for repeated patterns */
@utility btn-primary {
padding-inline: calc(var(--spacing) * 4);
padding-block: calc(var(--spacing) * 2);
background-color: var(--color-blue-500);
color: white;
border-radius: 0.375rem;
&:hover {
background-color: var(--color-blue-600);
}
}
@utility card {
background-color: white;
border-radius: 0.5rem;
box-shadow: var(--shadow-sm);
padding: calc(var(--spacing) * 6);
}
<!-- Use extracted utilities -->
<button class="btn-primary">Button</button>
<div class="card">Card content</div>

Version Information

  • Tailwind CSS 4.0+: Current stable version
  • Browser Support: Safari 16.4+, Chrome 111+, Firefox 128+
  • Node.js: 20+ (for upgrade tool)
  • PostCSS: Built-in (via @tailwindcss/postcss)
  • Vite Plugin: @tailwindcss/vite (recommended)

Key Changes from v3 πŸ“

v3v4
@tailwind directives@import "tailwindcss"
JavaScript configCSS @theme configuration
Manual content configAutomatic content detection
bg-gradient-*bg-linear-*
shadow-smshadow-xs
shadowshadow-sm
rounded-smrounded-xs
roundedrounded-sm
outline-noneoutline-hidden
ring (3px)ring-3 (1px default)
Arbitrary values for spacingDynamic spacing values
Container queries pluginBuilt-in container queries

Migration Notes πŸ“

Terminal window
# Use the official upgrade tool
npx @tailwindcss/upgrade
# Or upgrade manually:
# 1. Update dependencies
pnpm add tailwindcss @tailwindcss/postcss
# 2. Update PostCSS config
# 3. Replace @tailwind directives with @import "tailwindcss"
# 4. Migrate config to @theme
# 5. Update renamed utilities

⚠️ Critical: Tailwind CSS v4 requires modern browsers. If you need to support older browsers, stick with v3.4.