Tailwind CSS

Spacing

Layout

Typography

Colors & Effects

Tailwind CLI Simplest

The standalone CLI requires no Node.js. Download the binary or use npx.

# Install via npm
npm install -D tailwindcss
npx tailwindcss init

# Build your CSS
npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch

# Or use the standalone CLI (no Node required)
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64
chmod +x tailwindcss-linux-x64
./tailwindcss-linux-x64 -i input.css -o output.css

PostCSS Plugin Most Common

Integrates Tailwind into any PostCSS-based build pipeline.

# Install dependencies
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Vite Integration Modern

First-class support for Vite, Next.js, Nuxt, SvelteKit, and other modern frameworks.

# Vite + React example
npm create vite@latest my-app -- --template react
cd my-app
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p   # creates both config files

/* src/index.css — add the Tailwind directives */
@tailwind base;
@tailwind components;
@tailwind utilities;

Content Configuration

Tell Tailwind where your templates are so it can tree-shake unused classes.

// tailwind.config.js
module.exports = {
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx,vue,svelte}',
    './components/**/*.html',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

CDN (Play / Prototyping) Dev Only

For quick experiments. Not recommended for production.

<script src="https://cdn.tailwindcss.com"></script>

<!-- Customize the config inline -->
<script>
  tailwind.config = {
    theme: {
      extend: {
        colors: { brand: '#0ea5e9' }
      }
    }
  }
</script>

Traditional CSS vs. Utility-First

/* styles.css */
.card {
  background: white;
  border-radius: 0.5rem;
  padding: 1.5rem;
  box-shadow: 0 1px 3px
    rgba(0,0,0,0.1);
}
.card-title {
  font-size: 1.25rem;
  font-weight: 600;
  color: #1f2937;
}

<div class="
  bg-white
  rounded-lg
  p-6
  shadow
">
  <h2 class="
    text-xl
    font-semibold
    text-gray-800
  ">
    Title
  </h2>
</div>

Why Utility-First?

• No naming overhead — Stop inventing class names like .card-wrapper-inner. The utility describes exactly what it does.
• CSS stops growing — With traditional CSS, your stylesheet grows with every feature. With utilities, the same classes are reused across the entire project.
• Safe to change — Changing a utility class in HTML is local. You never worry about breaking something else by editing shared CSS.
• Consistent design — Utilities are constrained to your design system's scale. p-4 is always 1rem, not "whatever padding this component needs".
• Responsive & state variants — Apply styles conditionally with prefixes: md:flex, hover:bg-blue-600, dark:text-white.

The "Ugly HTML" Objection

A common criticism is that utility classes make HTML verbose. In practice:

• Components solve it — In React/Vue/Svelte, you write the utility classes once in a component and reuse the component.
• @apply for extraction — Pull repeated utility patterns into custom classes when needed.
• Multi-cursor editing — Modern editors make it easy to change classes across multiple instances.
• CSS purging keeps output tiny — Tailwind's production CSS is typically 5-10 KB gzipped, regardless of how many utilities exist.

The Default Spacing Scale

Spacing Prefixes

Width & Height

Color Palette (Selection)

Color Usage Patterns

Opacity Modifier

Append a slash and opacity value to any color utility.

<!-- Background with 50% opacity -->
<div class="bg-black/50">Semi-transparent overlay</div>

<!-- Text with 75% opacity -->
<p class="text-white/75">Slightly faded text</p>

<!-- Border with 20% opacity -->
<div class="border border-white/20"></div>

Custom Colors in Config

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        // Simple single color
        brand: '#0ea5e9',

        // Full shade scale
        brand: {
          50:  '#f0f9ff',
          100: '#e0f2fe',
          500: '#0ea5e9',
          900: '#0c4a6e',
        },

        // Using CSS variables (v3.1+)
        primary: 'rgb(var(--color-primary) / <alpha-value>)',
      },
    },
  },
}

Font Size Scale

Font Weight & Family

Text Utilities

Custom Fonts

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        display: ['Lexend', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
}

<!-- Usage: -->
<h1 class="font-display text-4xl">Custom Heading</h1>

Flexbox

<!-- Centered row with space between -->
<nav class="flex items-center justify-between px-6 py-4">
  <div class="font-bold text-xl">Logo</div>
  <div class="flex gap-4">
    <a href="#">Home</a>
    <a href="#">About</a>
  </div>
</nav>

CSS Grid

<!-- Responsive card grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  <div class="bg-white rounded-xl p-6 shadow-sm">Card 1</div>
  <div class="bg-white rounded-xl p-6 shadow-sm">Card 2</div>
  <div class="bg-white rounded-xl p-6 shadow-sm">Card 3</div>
</div>

<!-- 12-column layout -->
<div class="grid grid-cols-12 gap-4">
  <aside class="col-span-3">Sidebar</aside>
  <main class="col-span-9">Content</main>
</div>

Positioning

Default Breakpoints

Mobile-First in Practice

<!-- Stacked on mobile, side-by-side on md+, 3 columns on lg+ -->
<div class="
  flex flex-col          <!-- mobile: column -->
  md:flex-row            <!-- md+: row -->
  gap-4
">
  ...
</div>

<!-- Responsive text size -->
<h1 class="text-2xl md:text-4xl lg:text-6xl font-bold">
  Responsive Heading
</h1>

<!-- Show/hide based on screen size -->
<nav class="hidden md:flex gap-4">Desktop nav</nav>
<button class="md:hidden">Menu</button>

Custom Breakpoints

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      sm: '480px',    // override default
      md: '768px',
      lg: '1024px',
      xl: '1280px',
      '2xl': '1536px',
      '3xl': '1920px',  // custom addition
    },
  },
}

// Max-width breakpoints (v3.2+)
module.exports = {
  theme: {
    screens: {
      'max-md': { max: '767px' },
      'tablet': { min: '768px', max: '1023px' },
    },
  },
}

Container

<!-- Centered, responsive max-width container -->
<div class="container mx-auto px-4">
  <!-- sm: max-width 640px, md: 768px, lg: 1024px, etc. -->
</div>

// Customize container behavior
module.exports = {
  theme: {
    container: {
      center: true,
      padding: '2rem',
      screens: {
        '2xl': '1400px',  // cap at 1400px on large screens
      },
    },
  },
}

Pseudo-Class Variants

Interactive Button Example

<button class="
  bg-sky-500
  hover:bg-sky-600
  active:bg-sky-700
  focus-visible:ring-2 focus-visible:ring-sky-300 focus-visible:outline-none
  disabled:opacity-50 disabled:cursor-not-allowed
  text-white font-semibold
  px-6 py-2.5 rounded-lg
  transition-colors duration-150
">
  Click me
</button>

Group & Peer Variants

Style elements based on the state of a parent (group) or sibling (peer).

<!-- Group: style children when parent is hovered -->
<a href="#" class="group block p-4 rounded-lg hover:bg-sky-50">
  <h3 class="font-semibold group-hover:text-sky-600">Title</h3>
  <p class="text-gray-500 group-hover:text-gray-700">Description</p>
  <span class="text-sky-500 opacity-0 group-hover:opacity-100 transition">&rarr;</span>
</a>

<!-- Peer: style based on sibling state -->
<input type="email" class="peer ..." placeholder="Email" />
<p class="hidden peer-invalid:block text-red-500 text-sm">
  Please enter a valid email
</p>

Other Useful Variants

Two Strategies

// tailwind.config.js
module.exports = {
  darkMode: 'media',
}

// tailwind.config.js
module.exports = {
  darkMode: 'class',
}

// Or 'selector' in v3.4+
darkMode: 'selector',

Dark Mode in Practice

<div class="
  bg-white         dark:bg-slate-900
  text-gray-900    dark:text-white
  border-gray-200  dark:border-slate-700
  rounded-xl p-6 border
">
  <h2 class="text-xl font-bold">Card Title</h2>
  <p class="text-gray-600 dark:text-gray-400">
    This card adapts to dark mode automatically.
  </p>
</div>

Dark Mode Toggle (JS)

// Toggle dark mode with class strategy
const toggle = () => {
  const html = document.documentElement;
  html.classList.toggle('dark');
  localStorage.setItem('theme',
    html.classList.contains('dark') ? 'dark' : 'light'
  );
};

// Restore on page load (put in <head> to prevent flash)
if (localStorage.theme === 'dark' ||
    (!('theme' in localStorage) &&
     window.matchMedia('(prefers-color-scheme: dark)').matches)) {
  document.documentElement.classList.add('dark');
}

Config Structure

// tailwind.config.js (v3)
const defaultTheme = require('tailwindcss/defaultTheme');

module.exports = {
  content: ['./src/**/*.{html,js,jsx,tsx}'],
  darkMode: 'class',
  theme: {
    // Override defaults entirely
    screens: {
      sm: '480px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
    },
    extend: {
      // Add to defaults (don't replace)
      colors: {
        brand: {
          50:  '#f0f9ff',
          500: '#0ea5e9',
          900: '#0c4a6e',
        },
      },
      fontFamily: {
        sans: ['Inter', ...defaultTheme.fontFamily.sans],
      },
      spacing: {
        '18': '4.5rem',
        '128': '32rem',
      },
      borderRadius: {
        '4xl': '2rem',
      },
      animation: {
        'fade-in': 'fadeIn 0.5s ease-out',
      },
      keyframes: {
        fadeIn: {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' },
        },
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
    require('@tailwindcss/container-queries'),
  ],
}

Extend vs. Override

JIT Mode (Just-In-Time)

Since Tailwind v3, JIT is the default engine. It generates styles on-demand as you author classes, enabling:

• Instant build times — Only generates CSS for classes you actually use
• Arbitrary values — w-[137px], bg-[#1a1a2e], grid-cols-[200px_1fr]
• All variants enabled — No need to configure which variants are active
• Development and production parity — Same CSS in both environments

Presets

Share configuration across projects using presets.

// company-preset.js
module.exports = {
  theme: {
    extend: {
      colors: { brand: '#0ea5e9' },
      fontFamily: { sans: ['Inter'] },
    },
  },
}

// tailwind.config.js
module.exports = {
  presets: [require('./company-preset')],
  // project-specific overrides on top
}

@apply Directive

Pull utility classes into custom CSS.

/* In your CSS file */
@layer components {
  .btn {
    @apply px-4 py-2 font-semibold rounded-lg
           transition-colors duration-150;
  }

  .btn-primary {
    @apply btn bg-sky-500 text-white
           hover:bg-sky-600 active:bg-sky-700;
  }

  .btn-secondary {
    @apply btn bg-slate-200 text-slate-800
           hover:bg-slate-300;
  }

  .card {
    @apply bg-white dark:bg-slate-800
           rounded-xl shadow-md p-6
           border border-gray-200 dark:border-slate-700;
  }

  .input {
    @apply w-full rounded-lg border border-gray-300
           px-3 py-2 text-sm
           focus:ring-2 focus:ring-sky-500 focus:border-sky-500
           dark:bg-slate-900 dark:border-slate-600;
  }
}

CSS Layers

Tailwind has three layers that control specificity and ordering.

@layer base {
  h1 { @apply text-3xl font-bold; }
  h2 { @apply text-2xl font-semibold; }
  a  { @apply text-sky-500 hover:text-sky-600; }
}

@layer utilities {
  .text-shadow {
    text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.1);
  }
}

When to Use @apply

Arbitrary Values

Use square brackets to set any value for existing utility types.

<!-- Exact widths and heights -->
<div class="w-[137px] h-[calc(100vh-80px)]"></div>

<!-- Custom colors -->
<div class="bg-[#1a1a2e] text-[rgb(255,200,0)]"></div>

<!-- Grid template columns -->
<div class="grid grid-cols-[200px_1fr_200px]"></div>

<!-- Font sizes -->
<h1 class="text-[clamp(1.5rem,4vw,3rem)]">Fluid text</h1>

<!-- Margin with CSS variables -->
<div class="mt-[var(--header-height)]"></div>

<!-- Responsive arbitrary values -->
<div class="w-full md:w-[720px] lg:w-[960px]"></div>

Arbitrary Properties

Use any CSS property, even ones Tailwind doesn't have a built-in utility for.

<!-- Any CSS property -->
<div class="[mask-type:alpha]"></div>

<!-- Complex backdrop filter -->
<div class="[backdrop-filter:blur(12px)_saturate(180%)]"></div>

<!-- Scroll behavior -->
<div class="[scroll-snap-type:x_mandatory]"></div>

<!-- With variants -->
<div class="hover:[transform:rotateY(180deg)]"></div>

Arbitrary Variants

Target any CSS selector using bracket syntax.

<!-- Style a child element -->
<div class="[&_p]:text-gray-600">
  <p>This paragraph is gray</p>
</div>

<!-- nth-child -->
<ul class="[&>:nth-child(3)]:underline">...</ul>

<!-- Data attributes -->
<div class="[&[data-active]]:bg-sky-100"></div>

<!-- @supports query -->
<div class="[@supports(display:grid)]:grid"></div>

Official Plugins

<article class="prose lg:prose-xl">
  {{ markdown_content }}
</article>

<input type="text"
  class="rounded-md border-gray-300
  focus:ring-sky-500">

<div class="@container">
  <div class="@md:flex
    @lg:grid-cols-2">
  </div>
</div>

<div class="aspect-w-16
  aspect-h-9">
  <iframe ...></iframe>
</div>

Writing a Plugin

const plugin = require('tailwindcss/plugin');

module.exports = {
  plugins: [
    plugin(function({ addUtilities, addComponents, matchUtilities, theme }) {
      // Add static utilities
      addUtilities({
        '.text-shadow-sm': {
          textShadow: '0 1px 2px rgba(0,0,0,0.1)',
        },
        '.text-shadow-lg': {
          textShadow: '0 4px 8px rgba(0,0,0,0.2)',
        },
      });

      // Add dynamic utilities (generates from theme values)
      matchUtilities(
        {
          'text-shadow': (value) => ({
            textShadow: value,
          }),
        },
        { values: theme('textShadow') }
      );

      // Add component classes
      addComponents({
        '.btn': {
          padding: '.5rem 1rem',
          borderRadius: '.25rem',
          fontWeight: '600',
        },
      });
    }),
  ],
}

Popular Community Plugins

Navbar

<nav class="flex items-center justify-between px-6 py-4
     bg-white/80 backdrop-blur-md border-b border-gray-200
     sticky top-0 z-50">
  <a class="text-xl font-bold text-gray-900">Logo</a>
  <div class="hidden md:flex items-center gap-6">
    <a class="text-gray-600 hover:text-gray-900 transition">Features</a>
    <a class="text-gray-600 hover:text-gray-900 transition">Pricing</a>
    <a class="bg-sky-500 text-white px-4 py-2 rounded-lg
       hover:bg-sky-600 transition">Get Started</a>
  </div>
</nav>

Card with Image

<div class="group overflow-hidden rounded-2xl bg-white shadow-md
     hover:shadow-xl transition-shadow duration-300">
  <img class="w-full h-48 object-cover
       group-hover:scale-105 transition-transform duration-300"
       src="..." alt="..." />
  <div class="p-6">
    <span class="text-xs font-medium uppercase tracking-wide
           text-sky-600">Category</span>
    <h3 class="text-lg font-semibold text-gray-900 mt-2">Title</h3>
    <p class="text-gray-600 mt-2 line-clamp-2">Description...</p>
  </div>
</div>

Form with Validation States

<form class="space-y-6 max-w-md mx-auto">
  <div>
    <label class="block text-sm font-medium text-gray-700 mb-1">
      Email
    </label>
    <input type="email" class="
      w-full rounded-lg border border-gray-300
      px-3 py-2 text-sm shadow-sm
      placeholder:text-gray-400
      focus:outline-none focus:ring-2 focus:ring-sky-500 focus:border-sky-500
      invalid:border-red-500 invalid:ring-red-500
    " />
  </div>
  <button class="
    w-full bg-sky-500 text-white font-semibold
    py-2.5 px-4 rounded-lg shadow-sm
    hover:bg-sky-600 focus-visible:outline focus-visible:outline-2
    focus-visible:outline-offset-2 focus-visible:outline-sky-500
    disabled:opacity-50 disabled:cursor-not-allowed
  ">Submit</button>
</form>

Centered Hero Section

<section class="relative isolate overflow-hidden
         bg-gradient-to-b from-sky-50 to-white
         px-6 py-24 sm:py-32 lg:px-8">
  <div class="mx-auto max-w-2xl text-center">
    <p class="text-sm font-semibold text-sky-600 uppercase
       tracking-wide">Introducing v4</p>
    <h1 class="mt-2 text-4xl font-bold tracking-tight
       text-gray-900 sm:text-6xl text-balance">
      Build faster, ship sooner
    </h1>
    <p class="mt-6 text-lg leading-8 text-gray-600">
      A utility-first CSS framework packed with classes
      that can be composed to build any design.
    </p>
    <div class="mt-10 flex items-center justify-center gap-4">
      <a class="bg-sky-500 text-white px-6 py-3 rounded-xl
         font-semibold shadow-lg hover:bg-sky-600">Get Started</a>
      <a class="text-gray-700 font-semibold">Docs &rarr;</a>
    </div>
  </div>
</section>

What Changed v4

• CSS-first configuration — No more tailwind.config.js. Configure everything in CSS with @theme.
• Zero-config content detection — Automatic source detection, no content array needed.
• New high-performance engine — Full builds up to 10x faster, incremental builds 100x+ faster.
• CSS import via @import "tailwindcss" — Replaces the three @tailwind directives.
• Native CSS cascade layers — Uses @layer from the CSS spec, not Tailwind's custom @layer.
• Built-in @starting-style — Entry animations without JS.
• Container queries built in — No plugin needed. Use @sm:, @md:, etc.
• New 3D transform utilities — rotate-x-*, rotate-y-*, perspective-*.
• Modernized P3 color palette — Colors use oklch for wider gamut displays.

@theme Directive (CSS-First Config)

/* v4: Configure your design system in CSS */
@import "tailwindcss";

@theme {
  /* Colors */
  --color-brand-50: #f0f9ff;
  --color-brand-500: #0ea5e9;
  --color-brand-900: #0c4a6e;

  /* Fonts */
  --font-sans: "Inter", sans-serif;
  --font-display: "Lexend", sans-serif;

  /* Breakpoints */
  --breakpoint-sm: 480px;
  --breakpoint-3xl: 1920px;

  /* Custom spacing */
  --spacing-18: 4.5rem;

  /* Animations */
  --animate-fade-in: fadeIn 0.5s ease-out;
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

v3 to v4 Migration

module.exports = {
  content: ['./src/**/*.tsx'],
  theme: {
    extend: {
      colors: {
        brand: '#0ea5e9',
      },
    },
  },
}

@import "tailwindcss";

@theme {
  --color-brand: #0ea5e9;
}

/* Content detection
   is automatic! */

Renamed & Removed Utilities

Installation (v4)

# Install Tailwind CSS v4
npm install tailwindcss@next @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';

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

/* src/app.css — one line replaces the three @tailwind directives */
@import "tailwindcss";

Upgrade Tool

# Automated codemod for migrating from v3 to v4
npx @tailwindcss/upgrade@next

# What it does:
# - Converts tailwind.config.js to @theme in CSS
# - Updates deprecated class names
# - Replaces @tailwind directives with @import
# - Updates PostCSS config

Typography Plugin (v4)

In v4, the typography plugin is built into Tailwind. The prose class works without installing any plugin.

/* v4: just import Tailwind, prose is built in */
@import "tailwindcss";

<!-- Usage is the same -->
<article class="prose lg:prose-xl dark:prose-invert">
  <h1>My Blog Post</h1>
  <p>Beautiful default typography...</p>
</article>

<!-- Customize prose colors via @theme -->
@theme {
  --color-prose-body: var(--color-gray-700);
  --color-prose-headings: var(--color-gray-900);
  --color-prose-links: var(--color-sky-600);
}