Tailwind CSS Documentation
Utility-first CSS — style anything with small classes, responsive prefixes, dark mode and a design scale.
Tailwind CSS is a utility-first CSS framework. Instead of writing custom CSS classes, you style elements with small single-purpose classes right in your HTML/JSX: flex, p-4, text-lg, bg-blue-600, rounded-xl. Tailwind scans your files and generates only the CSS you use, so the final file is tiny.
1. Introduction & Setup
With Vite (React, Vue, plain HTML) — Tailwind v4:
npm create vite@latest my-app -- --template react
cd my-app
npm install tailwindcss @tailwindcss/vite
// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [react(), tailwindcss()] });
/* src/index.css */
@import "tailwindcss";
export default function App() {
return <h1 className="text-3xl font-bold text-blue-600">Hello Tailwind!</h1>;
}
Next.js: choose "Tailwind CSS: Yes" in create-next-app. Quick try without a build: the Play CDN <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script> (not for production).
Why utility-first?
| Traditional CSS | Tailwind |
|---|---|
invent class names (.card-header-title) |
no naming — style in place |
| CSS grows forever, dead styles pile up | only used classes are generated |
| jump between files | style and markup together |
| inconsistent spacing/colours | a fixed design scale |
⚠️ Common issue: classes have no effect → the CSS file with
@import "tailwindcss";isn't imported in your entry file, or (v3) the file isn't listed incontentoftailwind.config.js.
2. Core Concepts & Spacing
Class pattern: property-value. The spacing scale is in steps of 0.25rem (4px): 1 = 4px, 2 = 8px, 4 = 16px, 8 = 32px.
| Class | CSS |
|---|---|
p-4 |
padding: 1rem |
px-6 / py-2 |
horizontal / vertical padding |
pt-2 pr-3 pb-4 pl-5 |
single sides |
m-4, mx-auto, -mt-2 |
margin, centre horizontally, negative margin |
space-y-4 |
vertical gap between children |
gap-4 |
gap in flex/grid |
w-64, w-full, w-1/2, max-w-3xl |
widths |
h-screen, min-h-screen, h-10 |
heights |
size-10 |
width and height together |
Arbitrary values when the scale doesn't have it:
<div class="w-[350px] mt-[13px] bg-[#1da1f2] grid-cols-[200px_1fr]"></div>
3. Typography & Colours
<h1 class="text-4xl font-extrabold tracking-tight text-slate-900">Title</h1>
<p class="text-base leading-relaxed text-slate-600">Body text</p>
<a class="text-blue-600 underline underline-offset-4 hover:text-blue-800">Link</a>
<p class="truncate">Very long text that gets cut with an ellipsis…</p>
| Group | Classes |
|---|---|
| Size | text-xs sm base lg xl 2xl … 9xl |
| Weight | font-light normal medium semibold bold extrabold |
| Align | text-left center right justify |
| Line height | leading-tight snug normal relaxed loose |
| Transform | uppercase lowercase capitalize |
| Font | font-sans font-serif font-mono |
Colours come in shades 50 → 950: bg-blue-50 (very light) … bg-blue-950 (very dark). Palettes: slate, gray, zinc, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.
<div class="bg-emerald-100 text-emerald-800 border border-emerald-300">Saved!</div>
<div class="bg-black/50">50% opacity black overlay</div>
4. Flexbox & Grid
<!-- navbar: logo left, links right, vertically centred -->
<nav class="flex items-center justify-between px-6 py-4">
<span class="font-bold">Codify</span>
<ul class="flex gap-6">
<li>Notes</li><li>Practice</li><li>Contests</li>
</ul>
</nav>
<!-- centre anything -->
<div class="flex min-h-screen items-center justify-center">…</div>
| Flex | Meaning |
|---|---|
flex, inline-flex |
flex container |
flex-row / flex-col |
direction |
justify-start center between around evenly |
main axis |
items-start center end stretch baseline |
cross axis |
flex-wrap |
wrap items |
flex-1, grow, shrink-0 |
grow / don't shrink |
<!-- responsive card grid: 1 → 2 → 3 columns -->
<div class="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
<div class="rounded-xl border p-5">Card</div>
…
</div>
<!-- sidebar layout -->
<div class="grid grid-cols-[240px_1fr]">…</div>
<div class="col-span-2">spans two columns</div>
5. Responsive Design
Tailwind is mobile-first: classes without a prefix apply to all sizes; a prefix applies from that width up.
| Prefix | Min width |
|---|---|
sm: |
640px |
md: |
768px |
lg: |
1024px |
xl: |
1280px |
2xl: |
1536px |
<div class="text-sm md:text-base lg:text-lg">grows with the screen</div>
<div class="flex flex-col md:flex-row">stacked on phones, side by side from tablets</div>
<aside class="hidden lg:block">only on large screens</aside>
<button class="w-full sm:w-auto">full width on phones</button>
Max-width variants exist too: max-md:hidden hides below 768px.
6. States: Hover, Focus & More
<button class="rounded-lg bg-indigo-600 px-4 py-2 text-white
hover:bg-indigo-700 active:scale-95
focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600
disabled:cursor-not-allowed disabled:opacity-50">
Submit
</button>
<input class="rounded border px-3 py-2 invalid:border-red-500 focus:ring-2 focus:ring-indigo-400" />
Style children based on a parent (group) or a sibling (peer):
<a href="#" class="group flex items-center gap-2">
Read more
<span class="transition group-hover:translate-x-1">→</span>
</a>
<input type="checkbox" class="peer" id="t" />
<label for="t" class="peer-checked:text-green-600">Done</label>
Other variants: first:, last:, odd:, even:, placeholder:, before:/after:, aria-expanded:, data-[state=open]:, motion-reduce:, print:.
7. Dark Mode
By default dark: follows the operating system setting (prefers-color-scheme):
<body class="bg-white text-slate-900 dark:bg-slate-950 dark:text-slate-100">
<div class="border-slate-200 dark:border-slate-800">…</div>
</body>
To toggle with a class on <html> (v4):
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
document.documentElement.classList.toggle('dark');
(In v3: darkMode: 'class' in tailwind.config.js.)
8. Customising the Theme
v4 — in CSS with @theme:
@import "tailwindcss";
@theme {
--color-brand-500: #6366f1;
--color-brand-600: #4f46e5;
--font-display: "Poppins", sans-serif;
--breakpoint-3xl: 1920px;
}
Now bg-brand-500, font-display and 3xl: work.
v3 — tailwind.config.js:
export default {
content: ['./index.html', './src/**/*.{js,jsx,ts,tsx}'],
theme: {
extend: {
colors: { brand: { 500: '#6366f1', 600: '#4f46e5' } },
fontFamily: { display: ['Poppins', 'sans-serif'] },
},
},
plugins: [],
};
Custom utilities and components:
@utility content-auto {
content-visibility: auto;
}
@layer components {
.btn-primary {
@apply rounded-lg bg-brand-600 px-4 py-2 font-semibold text-white hover:bg-brand-500;
}
}
Use @apply sparingly — prefer reusable components (React/Vue) over CSS classes.
9. Borders, Shadows, Effects & Animation
| Group | Classes |
|---|---|
| Border | border border-2 border-t border-slate-200 border-dashed |
| Radius | rounded rounded-md lg xl 2xl full |
| Shadow | shadow-sm shadow shadow-md lg xl 2xl shadow-none |
| Ring (focus outline) | ring-2 ring-indigo-500 ring-offset-2 |
| Opacity | opacity-50, colour /50 suffix |
| Position | relative absolute fixed sticky top-0 inset-0 z-10 |
| Overflow | overflow-hidden overflow-auto overflow-x-auto |
| Display | block inline-block hidden |
| Images | object-cover aspect-video aspect-square |
| Transition | transition duration-200 ease-in-out |
| Transform | scale-105 rotate-3 -translate-y-1 |
| Animation | animate-spin animate-ping animate-pulse animate-bounce |
| Effects | blur-sm backdrop-blur bg-gradient-to-r from-indigo-500 to-pink-500 (v4: bg-linear-to-r) |
<div class="sticky top-0 z-20 border-b bg-white/80 backdrop-blur">Glass navbar</div>
<div class="size-6 animate-spin rounded-full border-2 border-slate-300 border-t-indigo-600"></div>
10. Advanced Concepts & Best Practices
- Don't build class names dynamically. Tailwind finds classes by scanning text, so
`bg-${color}-500`won't be generated. Map to full names:
const colors = { success: 'bg-green-500', error: 'bg-red-500' };
<span className={colors[status]} />
- Conditional classes: use
clsxand fix conflicts withtailwind-merge:
import clsx from 'clsx';
import { twMerge } from 'tailwind-merge';
const cn = (...c) => twMerge(clsx(c));
<button className={cn('px-4 py-2 rounded', primary && 'bg-indigo-600 text-white', className)} />
- Long class lists: extract a component, not a CSS class. Install the Prettier plugin
prettier-plugin-tailwindcssto sort classes. - Accessibility: keep visible focus styles (
focus-visible:), usesr-onlyfor screen-reader-only text. - Plugins:
@tailwindcss/typography(proseclass for markdown/blog content),@tailwindcss/forms. - Component libraries built on Tailwind: shadcn/ui, Headless UI, daisyUI, Flowbite.
- v3 → v4: CSS-first config (
@theme), automatic content detection,@import "tailwindcss"instead of three@tailwinddirectives, faster engine; runnpx @tailwindcss/upgrade.
11. Examples with Output
Example 1 — Card
<div class="mx-auto max-w-sm rounded-2xl border border-slate-200 p-6 shadow-sm">
<span class="rounded-full bg-indigo-100 px-3 py-1 text-xs font-semibold text-indigo-700">DSA</span>
<h3 class="mt-3 text-lg font-bold">Binary Search</h3>
<p class="mt-1 text-sm text-slate-600">Find an item in a sorted array in O(log n).</p>
<button class="mt-4 w-full rounded-lg bg-indigo-600 py-2 font-semibold text-white hover:bg-indigo-700">Start</button>
</div>
Result: a centred white card with a rounded border, a small purple "DSA" pill, a bold title, grey description and a full-width purple button that darkens on hover.
Example 2 — Responsive hero
<section class="px-6 py-16 text-center md:py-24">
<h1 class="text-3xl font-extrabold md:text-5xl">Learn to code, <span class="text-indigo-600">free</span></h1>
<p class="mx-auto mt-4 max-w-xl text-slate-600">Notes, practice and contests in one place.</p>
<div class="mt-8 flex flex-col justify-center gap-3 sm:flex-row">
<a class="rounded-lg bg-indigo-600 px-6 py-3 text-white">Get started</a>
<a class="rounded-lg border px-6 py-3">Browse notes</a>
</div>
</section>
Result: on phones, the heading is 30px and buttons are stacked; from 640px the buttons sit side by side; from 768px the heading grows to 48px.
Example 3 — Generated CSS size
npx vite build
dist/assets/index-3f2a1c.css 9.84 kB │ gzip: 2.61 kB
Only the classes used in your files are generated.
12. Practice Problems
- Build a responsive navbar that shows links in a row from
md:and a hamburger menu on phones. - Make a pricing section with three cards in a grid (1 column on phones, 3 on desktop) with the middle card highlighted.
- Create a login form with focus rings, error states (
invalid:) and a disabled button. - Add a dark-mode toggle that switches a
darkclass on<html>and remembers the choice. - Define brand colours and a custom font with
@themeand use them across a page. - Build a sticky blurred header and a scrollable table with
overflow-x-auto. - Style a markdown blog post with
@tailwindcss/typography(prose dark:prose-invert). - Make a reusable
<Button variant="primary|outline" size="sm|md">component withclsx+tailwind-merge.
13. Interview Questions
1. What does utility-first mean?
Styling with many small single-purpose classes (p-4, flex) composed in the markup instead of writing custom CSS for each component.
2. Doesn't Tailwind make HTML messy? Class lists get long, but you avoid naming and dead CSS; long lists are handled by extracting components.
3. How does Tailwind keep CSS small? It scans source files and generates only the classes it finds.
4. How is responsive design done?
Mobile-first breakpoint prefixes (sm:, md:, lg:) that apply from that width upward.
5. Why don't dynamic class names like bg-${c}-500 work?
The scanner sees only complete class strings in the source; build-time generation can't evaluate runtime strings.
6. How do you customise colours and fonts?
With @theme CSS variables (v4) or theme.extend in tailwind.config.js (v3).
7. What are group and peer?
Variants that style an element based on a parent's (group-hover:) or previous sibling's (peer-checked:) state.
8. @apply — when to use it?
To reuse a set of utilities in CSS (e.g. for third-party markup). Prefer component extraction in JS frameworks.
9. Tailwind vs Bootstrap? Bootstrap gives ready-made components with a fixed look; Tailwind gives low-level utilities to build any design.
10. How do you implement dark mode?
dark: variants based on the system preference, or on a .dark class for a manual toggle.
14. Cheat Sheet & References
Layout
<!-- flex row, centred, with gaps -->
<div class="flex items-center justify-between gap-4"></div>
<!-- responsive grid -->
<div class="grid grid-cols-1 gap-6 md:grid-cols-3"></div>
<!-- centred container -->
<div class="mx-auto max-w-6xl px-4"></div>
<!-- full-screen centre -->
<div class="grid min-h-screen place-items-center"></div>
Spacing and size
<!-- padding, margin, width, height -->
<div class="p-4 px-6 py-2 m-4 mt-8 mx-auto"></div>
<div class="w-full max-w-md h-10 size-12 min-h-screen"></div>
<!-- arbitrary value -->
<div class="w-[350px] top-[72px]"></div>
Text and colour
<p class="text-sm md:text-lg font-semibold leading-relaxed tracking-tight"></p>
<p class="text-slate-600 bg-indigo-50 border-indigo-200"></p>
<p class="truncate line-clamp-2 uppercase underline"></p>
Effects
<div class="rounded-xl shadow-md ring-1 ring-black/5 opacity-90"></div>
<div class="transition duration-200 hover:-translate-y-1 hover:shadow-lg"></div>
<div class="bg-white/70 backdrop-blur sticky top-0 z-50"></div>
Variants
<!-- state and responsive prefixes -->
<button class="hover:bg-indigo-700 focus-visible:ring-2 disabled:opacity-50"></button>
<div class="hidden md:block lg:flex"></div>
<div class="dark:bg-slate-900 dark:text-white"></div>
<div class="group"><span class="group-hover:underline"></span></div>
Official documentation