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
- Core Concepts
- CSS-First Configuration
- Utility Classes
- Layout & Spacing
- Typography
- Colors & Backgrounds
- Borders & Effects
- Responsive Design
- State Variants
- Customization
- Advanced Features
- Best Practices
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 π§
# Using npmnpm install tailwindcss @tailwindcss/postcss
# Using pnpm (recommended)pnpm add tailwindcss @tailwindcss/postcss
# Using yarnyarn add tailwindcss @tailwindcss/postcssPostCSS Configuration π
// postcss.config.js or postcss.config.mjsexport default { plugins: { "@tailwindcss/postcss": {}, },};CSS Import (v4 Style) π¨
/* src/styles/global.css or input.css *//* Single import replaces @tailwind directives */@import "tailwindcss";Vite Plugin (Recommended) β‘
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
.gitignoreentries automatically - Ignores binary files (images, videos, etc.)
- No
contentarray 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
@themefor 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
@utilitydirectives - β
Use
@starting-stylefor 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
contentarray (automatic detection works!) - β Donβt use arbitrary values when dynamic values work
- β Donβt use
@tailwinddirectives (use@import "tailwindcss") - β Donβt use
postcss-importorautoprefixer(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(useoutline-hiddeninstead) - β Donβt use
ringwithout width (usering-3for 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 π
| v3 | v4 |
|---|---|
@tailwind directives | @import "tailwindcss" |
| JavaScript config | CSS @theme configuration |
| Manual content config | Automatic content detection |
bg-gradient-* | bg-linear-* |
shadow-sm | shadow-xs |
shadow | shadow-sm |
rounded-sm | rounded-xs |
rounded | rounded-sm |
outline-none | outline-hidden |
ring (3px) | ring-3 (1px default) |
| Arbitrary values for spacing | Dynamic spacing values |
| Container queries plugin | Built-in container queries |
Migration Notes π
# Use the official upgrade toolnpx @tailwindcss/upgrade
# Or upgrade manually:# 1. Update dependenciespnpm 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.