Tailwind CSSv4INTERMEDIATE

Tailwind CSS

Comprehensive Tailwind CSS v4 reference covering utility classes, dark mode, states, responsive design, colors, layout, typography, customization with @theme, and more.

12 min read

tailwindcssutility-classesresponsivestylingframeworkv4

Installation & Setup

Install Tailwind CSS v4 and configure your project.

Installation (v4)

Install Tailwind CSS v4 with Vite, PostCSS, or the CLI.

css

/* CDN (quickest way to try it) */
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

/* Install with Vite (recommended for projects) */
npm install tailwindcss @tailwindcss/vite

/* vite.config.ts */
import tailwindcss from "@tailwindcss/vite"
export default { plugins: [tailwindcss()] }

/* app.css - single import, no config file needed */
@import "tailwindcss";

💡 v4 is CSS-first — no tailwind.config.js needed, use @theme in CSS instead

⚡ Just @import "tailwindcss" replaces all three @tailwind directives from v3

📌 Tailwind v4 auto-detects your source files — no content config needed

🟢 Use the Vite plugin for the best DX with hot reload and fast builds

installsetupv4

Dark Mode

Style for light and dark color schemes using the dark: variant.

Dark Mode

Apply different styles in dark mode using the dark: variant.

html

<!-- Follows system preference by default -->
<div class="bg-white dark:bg-gray-900">
  <h1 class="text-gray-900 dark:text-white">Title</h1>
  <p class="text-gray-600 dark:text-gray-300">Text</p>
</div>

💡 Dark mode follows the OS preference by default - no config needed

⚡ Prefix any utility with dark: to apply it only in dark mode

📌 For manual toggle, override the dark variant with @custom-variant dark (&:where(.dark, .dark *)); then toggle a .dark class on <html>

🟢 Common pattern: pair light/dark values on the same element (bg-white dark:bg-gray-900)

dark-modethemevariant

States & Variants

Apply styles on hover, focus, active, and other interactive states.

Hover, Focus & Other States

Style elements based on pseudo-classes and interactive states.

html

<!-- Hover & focus -->
<button class="bg-blue-500 hover:bg-blue-600
               focus:outline-none focus:ring-2 focus:ring-blue-400">
  Button
</button>

<!-- Active, disabled, first/last child -->
<button class="active:scale-95 disabled:opacity-50">
  Submit
</button>
<li class="first:pt-0 last:pb-0">Item</li>

💡 Use focus-visible: instead of focus: for keyboard-only focus rings (better UX)

⚡ Combine states: hover:dark:bg-gray-700 applies on hover in dark mode

📌 disabled: automatically sets cursor-not-allowed if you add it alongside opacity

🟢 Use before: and after: with content-[""] to create decorative pseudo-elements

hoverfocusstatespseudo-classes

Group & Peer Modifiers

Style elements based on parent or sibling state.

html

<!-- Group — style children when parent is hovered -->
<div class="group rounded-lg p-4 hover:bg-gray-100">
  <h3 class="group-hover:text-blue-600">Title</h3>
  <p class="group-hover:text-gray-700">Description</p>
</div>

<!-- Peer — style based on sibling state -->
<input class="peer" type="checkbox" />
<span class="peer-checked:text-green-500">Enabled</span>

💡 group-hover: styles children when the group parent is hovered — no JS needed

⚡ Use named groups (group/card) when nesting groups inside each other

📌 The peer element MUST come before peer-* elements in the HTML — it only works forward

🟢 peer-checked: + sr-only creates custom checkboxes/toggles without JavaScript

grouppeermodifiersinteractive

Colors & Opacity

Use the color palette and opacity modifiers across all utilities.

Color System & Opacity

Apply colors with the built-in palette and opacity shorthand.

html

<!-- Colors use shade-50 to shade-950 -->
<p class="text-blue-500">Blue text</p>
<div class="bg-gray-100 border-gray-300">Box</div>

<!-- Opacity modifier — append /opacity -->
<div class="bg-blue-500/75">75% opacity blue</div>
<div class="bg-black/50">50% opacity black</div>
<div class="text-white/80">80% opacity white</div>

💡 Append /opacity to any color utility: bg-blue-500/50, text-white/80, ring-red-500/25

⚡ The color scale runs 50-950: use lower numbers for light, higher for dark

📌 In v4, use bg-(--my-var) shorthand to reference CSS custom properties directly

🟢 shadow-xl/20 sets shadow opacity — great for subtle, non-harsh shadows

colorsopacitypalette

Layout

Container, display, positioning, z-index, overflow, and columns.

Container & Display

Set container width, display type, and visibility.

html

<!-- Container — centers and max-widths content -->
<div class="container mx-auto px-4">...</div>

<!-- Display -->
<div class="block">Block</div>
<span class="inline-block">Inline block</span>
<div class="hidden">Hidden</div>
<div class="flex">Flex container</div>
<div class="grid">Grid container</div>

💡 hidden sets display:none; invisible sets visibility:hidden (keeps layout space)

⚡ Use columns-2/3 for magazine-style multi-column text flow

📌 overflow-auto only shows scrollbars when content overflows; scroll always shows them

🟢 container + mx-auto + px-4 is the standard centered layout pattern

containerdisplayoverflowcolumns

Positioning & Z-Index

Position elements and control stacking order.

html

<!-- Position -->
<div class="relative">
  <div class="absolute top-0 right-0">Badge</div>
</div>
<nav class="fixed top-0 w-full">Navbar</nav>
<nav class="sticky top-0">Sticky nav</nav>

<!-- Inset & z-index -->
<div class="inset-0">Full overlay</div>
<div class="z-10">Above</div>
<div class="z-50">Topmost</div>

💡 inset-0 is shorthand for top-0 right-0 bottom-0 left-0 — perfect for overlays

⚡ sticky top-0 makes an element stick to the top when scrolling past it

📌 absolute elements position relative to the nearest relative/absolute/fixed parent

🟢 Use -z-10 for negative z-index — places element behind the default layer

positionz-indexstickyfixed

Flexbox & Grid

Layout with flexbox and CSS grid utilities.

Flexbox

Flexible box layout for rows and columns.

html

<!-- Basic flex row -->
<div class="flex gap-4">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

<!-- Centered content -->
<div class="flex items-center justify-center h-screen">
  <p>Perfectly centered</p>
</div>

<!-- Column layout -->
<div class="flex flex-col gap-2">
  <div>Top</div>
  <div>Bottom</div>
</div>

💡 flex items-center justify-center is the classic centering pattern

⚡ Use flex-1 for items that should grow to fill available space equally

📌 shrink-0 prevents an item from shrinking — useful for fixed-size icons/buttons

🟢 gap-4 adds spacing between flex items without margin hacks

flexflexboxlayout

Grid

CSS Grid layout for complex two-dimensional layouts.

html

<!-- Basic grid -->
<div class="grid grid-cols-3 gap-4">
  <div>1</div> <div>2</div> <div>3</div>
</div>

<!-- Responsive grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  <div>Card</div>
</div>

💡 grid-cols-[repeat(auto-fit,minmax(250px,1fr))] is a responsive grid without breakpoints

⚡ col-span-full makes an item stretch across all columns — great for full-width sections

📌 place-items-center centers both horizontally and vertically in one class

🟢 Use grid-cols-[custom] with arbitrary values for non-standard column widths

gridlayoutcolumns

Spacing & Sizing

Padding, margin, width, height, and space between elements.

Padding & Margin

Control inner and outer spacing.

html

<!-- Padding (all sides, x, y, individual) -->
<div class="p-4">All sides</div>
<div class="px-4 py-2">Horizontal + vertical</div>
<div class="pt-8 pb-4">Top + bottom</div>

<!-- Margin -->
<div class="m-4">All sides</div>
<div class="mx-auto">Center horizontally</div>
<div class="mt-8 mb-4">Top + bottom</div>
<div class="-mt-4">Negative margin</div>

💡 Use gap-4 on flex/grid instead of space-x/y — gap is more reliable with wrapping

⚡ mx-auto centers a block element; ml-auto pushes it to the right

📌 divide-y adds borders between children — much cleaner than border-b on each item

🟢 Negative margins (-mt-4) let elements overlap — useful for overlapping cards/avatars

paddingmarginspacingdivide

Width, Height & Aspect Ratio

Set element dimensions and aspect ratios.

html

<!-- Width -->
<div class="w-full">100%</div>
<div class="w-1/2">50%</div>
<div class="w-64">16rem (256px)</div>
<div class="max-w-lg">Max width large</div>
<div class="min-w-0">Min width zero</div>

<!-- Height -->
<div class="h-screen">Full viewport</div>
<div class="h-full">Full parent</div>
<div class="min-h-screen">At least full viewport</div>

💡 h-dvh is the mobile-safe viewport height — accounts for browser chrome on phones

⚡ size-12 sets both width and height to 3rem — perfect for icons and avatars

📌 max-w-prose (65ch) is the ideal line length for readable body text

🟢 Use w-fit to make an element only as wide as its content

widthheightsizingaspect-ratio

Typography

Font sizing, weight, text color, decoration, alignment, and line clamp.

Font & Text

Control font size, weight, line height, and text styling.

html

<!-- Font size -->
<p class="text-sm">Small</p>
<p class="text-base">Base (1rem)</p>
<p class="text-xl">Extra large</p>
<p class="text-4xl font-bold">Heading</p>

<!-- Text color & decoration -->
<p class="text-gray-600">Gray text</p>
<a class="underline decoration-blue-500">Link</a>
<p class="line-through">Deleted</p>

💡 line-clamp-2 truncates text to 2 lines with an ellipsis — no CSS hacks needed

⚡ decoration-2 + underline-offset-4 creates modern-looking styled underlines

📌 text-shadow is new in v4 — supports color and opacity modifiers like text-shadow-lg/50

🟢 Use tracking-tight on large headings and tracking-wide on small uppercase labels

typographyfonttext

Text Alignment & Wrapping

Align text and control overflow behavior.

html

<!-- Alignment -->
<p class="text-left">Left aligned</p>
<p class="text-center">Centered</p>
<p class="text-right">Right aligned</p>

<!-- Wrapping & overflow -->
<p class="truncate">Truncate with ellipsis...</p>
<p class="text-wrap">Normal wrapping</p>
<p class="text-nowrap">No wrapping</p>
<p class="text-balance">Balanced line breaks</p>
<p class="break-words">Break long words</p>

💡 truncate is a shorthand that combines overflow-hidden + text-ellipsis + whitespace-nowrap

⚡ text-balance creates even line lengths — ideal for headings

📌 text-pretty avoids orphaned single words on the last line of paragraphs

🟢 Use text-start/text-end instead of text-left/text-right for RTL language support

alignmentwrappingtruncate

Backgrounds & Borders

Background colors, gradients, border radius, rings, and outlines.

Backgrounds & Gradients

Background colors, images, and gradient utilities.

html

<!-- Background color -->
<div class="bg-white dark:bg-gray-900">Card</div>
<div class="bg-blue-500/10">Subtle tint</div>

<!-- Gradients -->
<div class="bg-gradient-to-r from-blue-500 to-purple-500">
  Left to right gradient
</div>
<div class="bg-gradient-to-br from-pink-500 via-red-500 to-yellow-500">
  Three-color diagonal gradient
</div>

💡 Use via-color to add a mid-point color stop in gradients

⚡ bg-blue-500/10 creates a subtle tint — great for hover states and cards

📌 bg-fixed creates a parallax scrolling effect on background images

🟢 Gradient directions: to-r (right), to-b (bottom), to-br (bottom-right), etc.

backgroundsgradientsimages

Borders, Rings & Radius

Border styling, focus rings, outlines, and rounded corners.

html

<!-- Border -->
<div class="border border-gray-300">Default border</div>
<div class="border-2 border-blue-500">Thick colored</div>
<div class="border-b border-gray-200">Bottom only</div>

<!-- Rounded corners -->
<div class="rounded">Small radius</div>
<div class="rounded-lg">Large radius</div>
<div class="rounded-full">Pill/circle</div>

<!-- Ring (focus indicator) -->
<button class="ring-2 ring-blue-500">Ring</button>
<input class="focus:ring-2 focus:ring-blue-500" />

💡 ring-2 creates a focus ring using box-shadow — doesn't affect layout like border does

⚡ Use ring-offset-2 to add space between the element and its ring

📌 rounded-full on a square element creates a circle; on a rectangle creates a pill

🟢 inset-ring puts the ring inside the element — useful for image borders

bordersringsradiusoutline

Effects & Filters

Shadows, opacity, blend modes, and CSS filters.

Shadows, Opacity & Filters

Box shadows, opacity, and visual filters.

html

<!-- Box shadows -->
<div class="shadow-sm">Small shadow</div>
<div class="shadow-lg">Large shadow</div>
<div class="shadow-xl/20">20% opacity shadow</div>
<div class="shadow-blue-500/25">Colored shadow</div>

<!-- Opacity -->
<div class="opacity-50">50% transparent</div>

<!-- Filters -->
<img class="blur-sm" />
<img class="grayscale" />
<div class="backdrop-blur-md bg-white/30">Glass effect</div>

💡 shadow-xl/20 adds opacity to shadows — makes them subtle and professional

⚡ backdrop-blur-md + bg-white/30 creates the popular frosted glass effect

📌 Shadow colors (shadow-blue-500/25) create modern colored shadow effects

🟢 Use shadow-inner for inset shadows — great for pressed button states

shadowsopacityfiltersblurbackdrop

Transitions & Animations

Smooth transitions, keyframe animations, and transforms.

Transitions & Transforms

Animate property changes and transform elements.

html

<!-- Transition on hover -->
<button class="transition-colors duration-200 hover:bg-blue-600">
  Smooth color change
</button>

<!-- Scale on hover -->
<div class="transition-transform duration-300 hover:scale-105">
  Card
</div>

<!-- Transform -->
<div class="rotate-45">Rotated 45°</div>
<div class="translate-x-4">Moved right</div>

💡 transition-colors is more performant than transition-all — specify what you animate

⚡ hover:-translate-y-1 + hover:shadow-lg creates the classic "lift on hover" card effect

📌 duration-200 to duration-300 feels natural for most UI transitions

🟢 active:scale-95 creates a satisfying press-down effect on buttons

transitionstransformsanimations

Keyframe Animations

Built-in and custom keyframe animations.

html

<!-- Built-in animations -->
<div class="animate-spin">Spinning loader</div>
<div class="animate-pulse">Pulsing skeleton</div>
<div class="animate-bounce">Bouncing arrow</div>
<div class="animate-ping">Ping notification</div>

💡 animate-pulse is perfect for skeleton loading states — just add it to gray boxes

⚡ animate-ping creates a radar-like ping effect — great for notification badges

📌 Define custom animations in @theme with @keyframes in v4

🟢 Combine with conditionals: show animate-spin while loading, hide when done

animationskeyframesspinpulse

Responsive Design

Breakpoints, responsive patterns, and container queries.

Breakpoints & Responsive

Mobile-first responsive design with breakpoint prefixes.

html

<!-- Mobile-first: styles apply from that breakpoint UP -->
<div class="text-sm md:text-base lg:text-lg">
  Responsive text
</div>

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  Responsive grid
</div>

<div class="hidden md:block">Only visible on md+</div>
<div class="md:hidden">Only visible on mobile</div>

💡 Tailwind is mobile-first: unprefixed classes apply to all sizes, breakpoints add overrides

⚡ Use max-md: to target screens BELOW a breakpoint — replaces tricky max-width media queries

📌 @container queries (v4) make components responsive to their parent, not the viewport

🟢 Common pattern: flex-col on mobile + md:flex-row on desktop for stack-to-row layouts

responsivebreakpointscontainer-queries

Customization

Customize Tailwind with @theme, @apply, and arbitrary values.

@theme, @apply & Arbitrary Values

Extend the default theme, use utilities in custom CSS, and write one-off values.

css

/* @theme — customize colors, fonts, spacing (v4) */
@theme {
  --color-brand: #3b82f6;
  --font-display: "Inter", sans-serif;
}

/* @apply — use Tailwind utilities in custom CSS */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg;
}

/* Arbitrary values — one-off custom values */
<div class="w-[347px] bg-[#1a2b3c] top-[117px]">

💡 @theme replaces tailwind.config.js in v4 — everything is CSS-native now

⚡ Use @apply sparingly — it's best for repeated component patterns, not one-off styles

📌 @variant lets you use dark:, hover:, etc. inside custom CSS blocks

🟢 Arbitrary values [347px] are escape hatches for one-off values not in the scale

themeapplycustomizationarbitrary

@source, @plugin & @utility

Control source detection, load plugins, and define custom utilities — v4 CSS-first

css

/* @source — control which files Tailwind scans for classes */
@import "tailwindcss";
@source "../components";
@source "../node_modules/@my/ui";
@source not "./legacy/**";

/* @plugin — load a Tailwind plugin (replaces tailwind.config.js plugins array) */
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

/* @utility — define your own utility class */
@utility content-auto {
  content-visibility: auto;
}

/* @custom-variant — define a custom variant */
@custom-variant pointer-coarse (@media (pointer: coarse));

/* Now usable as: */
/* class="content-auto pointer-coarse:p-6" */

💡 @source adds extra scan paths; @source not excludes; @source inline safelists literals

⚡ @plugin loads plugins from CSS — no more JS config file just for plugins

📌 @utility makes custom utilities first-class and variant-aware automatically

🎯 @custom-variant + @reference round out the all-CSS authoring story

v4directivescustomization

Interactivity & Accessibility

Cursor, scroll behavior, screen readers, and tables.

Cursor, Scroll & Tables

Interactive behavior, scroll snap, and table styling.

html

<!-- Cursor -->
<button class="cursor-pointer">Clickable</button>
<div class="cursor-not-allowed opacity-50">Disabled</div>
<div class="cursor-grab active:cursor-grabbing">Drag me</div>

<!-- Scroll behavior -->
<div class="scroll-smooth">Smooth scrolling</div>
<div class="overflow-y-auto scrollbar-thin">Custom scrollbar</div>

<!-- Screen reader only -->
<span class="sr-only">Accessible label</span>

💡 sr-only hides content visually but keeps it accessible to screen readers

⚡ snap-x + snap-mandatory creates swipeable carousels without JavaScript

📌 scroll-mt-16 offsets anchor scroll targets — essential when you have a fixed header

🟢 accent-blue-500 styles native checkboxes and range inputs — no custom CSS needed

cursorscrollaccessibilitytablessvg

Tailwind CSS

Table of Contents

Installation & Setup

Installation (v4)

Dark Mode

Dark Mode

States & Variants

Hover, Focus & Other States

Group & Peer Modifiers

Colors & Opacity

Color System & Opacity

Layout

Container & Display

Positioning & Z-Index

Flexbox & Grid

Flexbox

Grid

Spacing & Sizing

Padding & Margin

Width, Height & Aspect Ratio

Typography

Font & Text

Text Alignment & Wrapping

Backgrounds & Borders

Backgrounds & Gradients

Borders, Rings & Radius

Effects & Filters

Shadows, Opacity & Filters

Transitions & Animations

Transitions & Transforms

Keyframe Animations

Responsive Design

Breakpoints & Responsive

Customization

@theme, @apply & Arbitrary Values

@source, @plugin & @utility

Interactivity & Accessibility

Cursor, Scroll & Tables