# Tailwind CSS User Guide
Tailwind CSS is a utility-first CSS framework that lets you build custom designs directly in your HTML using a fixed vocabulary of composable class names like `flex`, `px-4`, `text-lg`, and `bg-blue-500`. Version 4 is a ground-up rewrite: configuration now lives in your CSS through directives like `@theme`, `@source`, and `@plugin` rather than a JavaScript config file. The class scanner runs in Rust via the Oxide engine, and the default theme ships with a curated OKLCH color palette.
This guide covers everything you need to install, configure, and use Tailwind CSS in your projects. For architecture details, plugin authoring internals, Oxide scanner implementation, and monorepo layout, see the Admin Guide.
---
## 1. Quick Start
Get a working Tailwind CSS project in under two minutes.
### 1.1 The Fastest Path: Vite
```bash
npm create vite@latest my-project -- --template vanilla
cd my-project
npm install tailwindcss @tailwindcss/vite
```
Add the Vite plugin to `vite.config.js`:
```js
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
tailwindcss(),
],
})
```
Replace the contents of `src/style.css`:
```css
@import 'tailwindcss';
```
Add utility classes to your HTML:
```html
Hello, Tailwind!
```
Start the dev server:
```bash
npm run dev
```
That single `@import 'tailwindcss'` line pulls in Preflight (a modern CSS reset), the full default theme, and all utility class generation. Every class you use in your markup is detected automatically and compiled into your CSS output.
### 1.2 The Fastest Path: CLI
If you have no build tool at all:
```bash
npx @tailwindcss/cli -i input.css -o output.css --watch
```
Where `input.css` contains `@import 'tailwindcss';`. The CLI watches your project files and regenerates `output.css` whenever you save.
### 1.3 The Fastest Path: CDN (Browser Build)
For prototyping with zero tooling:
```html
Instant Tailwind
```
> [!WARNING]
> The browser build is for prototyping only. It compiles in the browser at runtime, does not support `@import` of external files, and does not support JS plugins or config files. Never use it in production.
---
## 2. Installation
Tailwind CSS v4 requires **Node.js 20 or later**. There are six integration paths depending on your build setup.
### 2.1 Requirements
| Requirement | Version |
|---|---|
| Node.js | >= 20 |
| npm / pnpm / yarn / bun | Any current release |
| License | MIT |
> [!NOTE]
> Tailwind v4 ships native binaries for the Oxide scanner. Supported platforms include Linux x64 (glibc and musl), Linux ARM64, macOS x64, macOS ARM64, and Windows x64. If your platform is not supported, you will see an error at install time (see Troubleshooting).
### 2.2 Using the Vite Plugin
The Vite plugin (`@tailwindcss/vite`) is the recommended integration for Vite-based projects. It provides the fastest development experience with hot module replacement (HMR).
```bash
npm install tailwindcss @tailwindcss/vite
```
```js
// vite.config.js
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
tailwindcss(),
],
})
```
Create your CSS entry point:
```css
/* src/app.css */
@import 'tailwindcss';
```
Import the CSS in your application entry:
```js
// src/main.js
import './app.css'
```
#### Vite Plugin with React
```bash
npm install tailwindcss @tailwindcss/vite
```
```js
// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
react(),
tailwindcss(),
],
})
```
#### Vite Plugin with Vue
```bash
npm install tailwindcss @tailwindcss/vite
```
```js
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
vue(),
tailwindcss(),
],
})
```
#### Vite Plugin with Svelte
```bash
npm install tailwindcss @tailwindcss/vite
```
```js
// vite.config.js
import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
svelte(),
tailwindcss(),
],
})
```
### 2.3 Using PostCSS
The PostCSS plugin (`@tailwindcss/postcss`) integrates Tailwind into any PostCSS-compatible build tool.
```bash
npm install tailwindcss @tailwindcss/postcss
```
Add to your PostCSS configuration:
```js
// postcss.config.js
export default {
plugins: {
'@tailwindcss/postcss': {},
},
}
```
Create your CSS entry point:
```css
/* src/app.css */
@import 'tailwindcss';
```
> [!TIP]
> If you are using a framework that already has PostCSS configured (like Next.js, Nuxt, or Angular), you only need to add `@tailwindcss/postcss` to the existing PostCSS config. You do not need to install PostCSS separately.
#### PostCSS with Next.js
```bash
npm install tailwindcss @tailwindcss/postcss
```
```js
// postcss.config.mjs
const config = {
plugins: {
'@tailwindcss/postcss': {},
},
}
export default config
```
In your global CSS file (e.g., `app/globals.css`):
```css
@import 'tailwindcss';
```
#### PostCSS with Nuxt
```bash
npm install tailwindcss @tailwindcss/postcss
```
```js
// postcss.config.js
export default {
plugins: {
'@tailwindcss/postcss': {},
},
}
```
In your Nuxt CSS entry (configured in `nuxt.config.ts`):
```css
@import 'tailwindcss';
```
#### PostCSS with Angular
```bash
npm install tailwindcss @tailwindcss/postcss
```
Angular's CLI reads `.postcssrc.json` automatically:
```json
{
"plugins": {
"@tailwindcss/postcss": {}
}
}
```
In your `src/styles.css`:
```css
@import 'tailwindcss';
```
### 2.4 Using the CLI
The CLI (`@tailwindcss/cli`) is a standalone build tool that requires no framework integration.
```bash
npm install tailwindcss @tailwindcss/cli
```
#### CLI Commands
| Command | Description |
|---|---|
| `build` (default) | Compile CSS input to output |
| `canonicalize` | Normalize and reformat Tailwind CSS input |
#### CLI Flags
| Flag | Short | Description |
|---|---|---|
| `--input` | `-i` | Path to the input CSS file |
| `--output` | `-o` | Path to write the compiled CSS |
| `--watch` | `-w` | Watch for changes and rebuild automatically |
| `--minify` | | Minify the output CSS |
| `--help` | `-h` | Show help information |
| `-` (stdin) | | Read input from stdin |
| `-` (stdout) | | Write output to stdout |
#### Basic Build
```bash
npx @tailwindcss/cli -i src/app.css -o dist/output.css
```
#### Watch Mode
```bash
npx @tailwindcss/cli -i src/app.css -o dist/output.css --watch
```
#### Minified Production Build
```bash
npx @tailwindcss/cli -i src/app.css -o dist/output.css --minify
```
#### Pipe via stdin/stdout
```bash
cat src/app.css | npx @tailwindcss/cli -i - -o -
```
This is useful for integrating with other tools in a Unix pipeline.
#### Canonicalize
The `canonicalize` command normalizes your Tailwind CSS file, reordering directives and formatting consistently:
```bash
npx @tailwindcss/cli canonicalize -i src/app.css -o src/app.css
```
#### Using with npm Scripts
```json
{
"scripts": {
"dev": "tailwindcss -i src/app.css -o dist/output.css --watch",
"build": "tailwindcss -i src/app.css -o dist/output.css --minify"
}
}
```
### 2.5 Using Webpack
The Webpack loader (`@tailwindcss/webpack`) integrates Tailwind into Webpack-based projects.
```bash
npm install tailwindcss @tailwindcss/webpack
```
```js
// webpack.config.js
const tailwindcss = require('@tailwindcss/webpack')
module.exports = {
// ...
plugins: [
tailwindcss(),
],
}
```
Create your CSS entry point:
```css
/* src/app.css */
@import 'tailwindcss';
```
### 2.6 Using the Standalone Binary
The standalone CLI (`@tailwindcss/standalone`) is a self-contained binary that does not require Node.js. It bundles everything needed to compile Tailwind CSS, including several popular first-party plugins.
#### Download
Download the binary for your platform from the GitHub releases page, or install it:
```bash
npm install @tailwindcss/standalone
```
#### Built-in Plugins
The standalone binary includes these plugins with no additional installation:
- `@tailwindcss/forms`
- `@tailwindcss/typography`
- `@tailwindcss/aspect-ratio`
#### Usage
```bash
./tailwindcss -i src/app.css -o dist/output.css --watch
```
The standalone binary accepts the same flags as the standard CLI (`--input`, `--output`, `--watch`, `--minify`).
> [!TIP]
> The standalone binary is ideal for environments where Node.js is not available or not desired, such as CI pipelines, Docker containers with minimal images, or non-Node projects (PHP, Ruby, Python, Go, etc.).
### 2.7 Using the Browser Build
The browser build (`@tailwindcss/browser`) compiles Tailwind CSS entirely in the browser at runtime.
```html
```
Or with a specific version:
```html
```
#### Inline Tailwind CSS
You can write Tailwind directives in a `
Hello
```
#### Browser Build Limitations
The browser build has specific constraints:
- `@import` for external files is not supported
- JS plugins (`@plugin`) are not supported
- JS config files (`@config`) are not supported
- Compilation happens at runtime (performance impact on page load)
- Not suitable for production use
### 2.8 Granular CSS Imports
Instead of importing all of Tailwind with `@import 'tailwindcss'`, you can import individual layers:
```css
/* Preflight only (CSS reset) */
@import 'tailwindcss/preflight';
/* Theme variables only */
@import 'tailwindcss/theme';
/* Utility classes only */
@import 'tailwindcss/utilities';
```
This gives you control over which parts of Tailwind are included. For example, if you already have your own CSS reset:
```css
/* Skip Preflight, use theme + utilities only */
@import 'tailwindcss/theme';
@import 'tailwindcss/utilities';
```
Or if you want to insert custom base styles between Preflight and utilities:
```css
@import 'tailwindcss/preflight';
@import 'tailwindcss/theme';
/* Your custom base styles here */
body {
font-family: 'Inter', sans-serif;
}
@import 'tailwindcss/utilities';
```
---
## 3. Configuration
Tailwind CSS v4 uses a **CSS-first configuration** model. Instead of a `tailwind.config.js` file, you configure Tailwind directly in your CSS using special directives.
### 3.1 Configuration Directives Overview
| Directive | Purpose |
|---|---|
| `@theme` | Define and override design tokens (colors, spacing, fonts, etc.) |
| `@source` | Control which files are scanned for class candidates |
| `@plugin` | Load JavaScript plugins |
| `@config` | Load a legacy `tailwind.config.js` file |
| `@variant` | Define custom variants |
| `@utility` | Define custom utility classes |
| `@apply` | Use utility classes inside custom CSS |
| `@reference` | Reference another CSS file without including its output |
### 3.2 The `@theme` Directive
The `@theme` directive defines design tokens as CSS custom properties. These tokens generate the utility classes Tailwind provides.
#### Basic Theme Customization
```css
@import 'tailwindcss';
@theme {
--color-primary: #3b82f6;
--color-secondary: #8b5cf6;
--color-accent: #f59e0b;
--font-family-display: 'Cal Sans', sans-serif;
--font-family-body: 'Inter', sans-serif;
}
```
This makes classes like `text-primary`, `bg-secondary`, `text-accent`, `font-display`, and `font-body` available throughout your project.
#### Namespace Prefixes
Theme values are organized by namespace prefix. Each prefix maps to a category of utilities:
| Prefix | Generates | Example Class |
|---|---|---|
| `--color-*` | Color utilities | `text-brand`, `bg-brand`, `border-brand` |
| `--spacing-*` | Spacing utilities | `p-gutter`, `m-gutter`, `gap-gutter` |
| `--font-family-*` | Font family utilities | `font-display` |
| `--font-size-*` | Font size utilities | `text-heading` |
| `--font-weight-*` | Font weight utilities | `font-medium` |
| `--breakpoint-*` | Responsive breakpoints | `md:`, `lg:`, `xl:` |
| `--width-*` | Width utilities | `w-sidebar` |
| `--height-*` | Height utilities | `h-header` |
| `--radius-*` | Border radius utilities | `rounded-card` |
| `--shadow-*` | Box shadow utilities | `shadow-card` |
| `--tracking-*` | Letter spacing utilities | `tracking-wide` |
| `--leading-*` | Line height utilities | `leading-relaxed` |
| `--ease-*` | Transition timing | `ease-bounce` |
| `--animate-*` | Animation utilities | `animate-slide-in` |
| `--inset-shadow-*` | Inset shadow utilities | `inset-shadow-lg` |
#### Defining Colors
```css
@theme {
--color-brand-50: #eff6ff;
--color-brand-100: #dbeafe;
--color-brand-200: #bfdbfe;
--color-brand-300: #93c5fd;
--color-brand-400: #60a5fa;
--color-brand-500: #3b82f6;
--color-brand-600: #2563eb;
--color-brand-700: #1d4ed8;
--color-brand-800: #1e40af;
--color-brand-900: #1e3a8a;
--color-brand-950: #172554;
}
```
This generates `text-brand-500`, `bg-brand-200`, `border-brand-700`, `ring-brand-400`, and all other color-related utilities for every shade.
#### Defining Spacing
```css
@theme {
--spacing-gutter: 1.5rem;
--spacing-section: 4rem;
--spacing-sidebar: 16rem;
}
```
Generates `p-gutter`, `m-section`, `gap-gutter`, `w-sidebar`, and so on.
#### Defining Breakpoints
```css
@theme {
--breakpoint-xs: 30rem;
--breakpoint-sm: 40rem;
--breakpoint-md: 48rem;
--breakpoint-lg: 64rem;
--breakpoint-xl: 80rem;
--breakpoint-2xl: 96rem;
}
```
Generates responsive variants like `xs:`, `sm:`, `md:`, `lg:`, `xl:`, `2xl:`.
#### Defining Fonts
```css
@theme {
--font-family-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
--font-family-serif: 'Merriweather', ui-serif, Georgia, serif;
--font-family-mono: 'JetBrains Mono', ui-monospace, monospace;
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.125rem;
--font-size-xl: 1.25rem;
--font-size-2xl: 1.5rem;
--font-size-3xl: 1.875rem;
--font-size-4xl: 2.25rem;
--font-weight-thin: 100;
--font-weight-light: 300;
--font-weight-normal: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
--font-weight-black: 900;
}
```
#### Defining Shadows
```css
@theme {
--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
--shadow-card: 0 2px 8px rgb(0 0 0 / 0.08);
--shadow-elevated: 0 8px 24px rgb(0 0 0 / 0.12);
}
```
#### Defining Animations
```css
@theme {
--animate-fade-in: fade-in 0.3s ease-out;
--animate-slide-up: slide-up 0.4s ease-out;
--animate-bounce-in: bounce-in 0.6s cubic-bezier(0.68, -0.55, 0.265, 1.55);
}
@keyframes fade-in {
from { opacity: 0; }
to { opacity: 1; }
}
@keyframes slide-up {
from { transform: translateY(1rem); opacity: 0; }
to { transform: translateY(0); opacity: 1; }
}
@keyframes bounce-in {
from { transform: scale(0.9); opacity: 0; }
to { transform: scale(1); opacity: 1; }
}
```
Generates `animate-fade-in`, `animate-slide-up`, `animate-bounce-in`.
#### Defining Transition Timing
```css
@theme {
--ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
--ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
}
```
Generates `ease-bounce`, `ease-smooth`.
#### Defining Border Radius
```css
@theme {
--radius-sm: 0.25rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--radius-xl: 0.75rem;
--radius-2xl: 1rem;
--radius-full: 9999px;
--radius-card: 0.75rem;
--radius-button: 0.5rem;
}
```
#### Resetting the Default Theme
To start from scratch with no default theme values, reset all defaults:
```css
@theme {
--*: initial;
}
```
This removes every built-in design token. You must then define all your own tokens from zero. Classes like `text-blue-500` will no longer work unless you re-define those color tokens.
You can also reset specific namespaces:
```css
@theme {
--color-*: initial;
/* Now define only the colors you want */
--color-primary: #3b82f6;
--color-gray-100: #f3f4f6;
--color-gray-900: #111827;
}
```
> [!IMPORTANT]
> Resetting with `--*: initial` removes ALL default Tailwind theme values. This means default colors like `blue-500`, default spacing, default breakpoints, and all other built-in tokens disappear. Only do this if you intend to define a complete custom design system.
#### Multiple `@theme` Blocks
You can use multiple `@theme` blocks. They merge together:
```css
@import 'tailwindcss';
@theme {
--color-primary: #3b82f6;
}
@theme {
--color-secondary: #8b5cf6;
}
```
Both `primary` and `secondary` colors will be available.
### 3.3 The `@source` Directive
The `@source` directive tells Tailwind which files to scan for utility class candidates. By default, Tailwind scans all files in your project directory (respecting `.gitignore`), but you can customize this.
#### Adding Source Paths
```css
@import 'tailwindcss';
@source '../components/**/*.jsx';
@source '../layouts/**/*.html';
@source '../node_modules/my-ui-lib/src/**/*.js';
```
#### Glob Pattern Syntax
| Pattern | Matches |
|---|---|
| `*` | Any file in a single directory |
| `**` | Any file recursively |
| `*.jsx` | Any `.jsx` file in a single directory |
| `**/*.{html,jsx,tsx}` | Any `.html`, `.jsx`, or `.tsx` file recursively |
| `../packages/ui/**/*.tsx` | Files in a sibling package |
#### Scanning Node Modules
By default, `node_modules` is excluded. To scan a specific package:
```css
@source '../node_modules/@my-org/ui-components/**/*.js';
```
#### Source Directory Base
The `source(...)` function references a directory that all `@source` glob patterns are relative to:
```css
@import 'tailwindcss' source('../src');
```
This changes the base directory for automatic scanning from your CSS file's location to `../src`.
> [!NOTE]
> The `@source` directive respects your `.gitignore` file. If a file or directory is listed in `.gitignore`, Tailwind will not scan it for class candidates even if it matches a `@source` glob pattern. This can cause confusion when `@source` appears to silently ignore paths (see Troubleshooting for issue #19844).
#### Source with `none`
Disable automatic source detection entirely:
```css
@import 'tailwindcss' source(none);
/* Only scan explicitly listed sources */
@source '../app/**/*.tsx';
@source '../components/**/*.tsx';
```
#### Scanning Non-Standard File Types
The Oxide engine automatically detects and extracts class candidates from many file types beyond HTML and JavaScript:
| Language/Format | File Extensions |
|---|---|
| Clojure | `.clj`, `.cljs`, `.cljc` |
| Elixir | `.ex`, `.exs`, `.heex`, `.leex` |
| Haml | `.haml` |
| JSON | `.json` |
| Markdown | `.md`, `.mdx` |
| Pug | `.pug`, `.jade` |
| Razor | `.cshtml`, `.razor` |
| Ruby | `.rb`, `.erb` |
| Rust | `.rs` |
| Slim | `.slim` |
| Svelte | `.svelte` |
| Vue | `.vue` |
### 3.4 The `@plugin` Directive
Load JavaScript plugins directly from your CSS:
```css
@import 'tailwindcss';
@plugin '@tailwindcss/typography';
@plugin '@tailwindcss/forms';
@plugin './my-custom-plugin.js';
```
Plugins must be installed in your `node_modules` or referenced as a relative path. Each plugin can register new utilities, variants, base styles, and components.
#### Popular First-Party Plugins
| Plugin | Purpose |
|---|---|
| `@tailwindcss/typography` | Beautiful typographic defaults for prose content |
| `@tailwindcss/forms` | Improved form element styling |
| `@tailwindcss/aspect-ratio` | Aspect ratio utilities (v3 compat) |
### 3.5 The `@config` Directive
For backward compatibility, you can load a legacy `tailwind.config.js` file:
```css
@import 'tailwindcss';
@config '../tailwind.config.js';
```
This is a migration path from v3. The CSS-first configuration (`@theme`, `@plugin`, etc.) is the recommended approach for new projects.
> [!TIP]
> Use the `@tailwindcss/upgrade` tool to automatically migrate your v3 `tailwind.config.js` to v4 CSS-first configuration. See the "Upgrading from Tailwind v3" section for details.
### 3.6 The `@reference` Directive
The `@reference` directive lets you reference another CSS file for type-checking and IntelliSense without actually including its output in your build:
```css
@reference '../app.css';
.my-component {
@apply text-primary bg-secondary;
}
```
This is useful when you have component-level CSS files that need access to your theme tokens and custom utilities defined in a different file, without duplicating that file's output.
### 3.7 Theme Functions
Tailwind v4 provides CSS functions for referencing theme values dynamically.
#### `--theme(...)`
Reference any theme token value:
```css
.custom-element {
color: var(--color-primary);
background-color: --theme(--color-brand-100);
border: 1px solid --theme(--color-brand-300);
}
```
> [!CAUTION]
> The `--theme(...)` function can only be used with CSS variables defined in your `@theme` block. Attempting to use it with non-theme variables produces: `The --theme(...) function can only be used with CSS variables from your theme.`
#### `--spacing(...)`
Reference the spacing scale:
```css
.custom-element {
padding: --spacing(4);
margin-bottom: --spacing(8);
gap: --spacing(2);
}
```
The argument maps to your spacing scale (e.g., `--spacing(4)` = `1rem` in the default theme). Passing no argument produces an error: `The --spacing(...) function requires an argument, but received none.`
### 3.8 Compatibility Exports
For backward compatibility with v3-era tooling and plugins, Tailwind CSS v4 provides these JavaScript exports:
| Export | Import Path |
|---|---|
| Default colors | `tailwindcss/colors` |
| Default theme values | `tailwindcss/defaultTheme` |
| Plugin helper | `tailwindcss/plugin` |
| Color utility | `tailwindcss/lib/util/flattenColorPalette` |
```js
// Accessing default colors in a plugin or config
import colors from 'tailwindcss/colors'
console.log(colors.blue[500]) // '#3b82f6'
```
```js
// Using the plugin helper
import plugin from 'tailwindcss/plugin'
export default plugin(function({ addUtilities }) {
addUtilities({
'.content-auto': {
'content-visibility': 'auto',
},
})
})
```
---
## 4. Core Usage
### 4.1 How Utility Classes Work
Every Tailwind utility class maps to one or a small number of CSS property declarations. You compose them in your HTML `class` attribute to build designs:
```html
Jane Smith
Product Designer
```
This renders a card with flexbox layout, centered items, a gap between children, padding, white background, rounded corners, and a shadow. No custom CSS written.
### 4.2 Layout Utilities
#### Flexbox
```html
```
Style siblings based on sibling state:
```html
Please enter a valid email address.
```
#### Dark Mode
```html
Heading
Body text
Card
Card content
```
Dark mode uses the `prefers-color-scheme` media query by default.
#### Print Variant
```html
Hidden when printing
Visible only when printing
```
#### Motion Variants
```html
Animated on hover (unless user prefers reduced motion)
```
#### Portrait and Landscape
```html
Hidden in portrait orientation
Hidden in landscape orientation
```
#### RTL and LTR
```html
Direction-aware alignment
```
#### Container Queries
```html
Container-query responsive layout
```
#### Stacking Variants
Variants can be stacked. They read left to right:
```html
Focus ring on large screens
```
### 4.11 Arbitrary Values
When the default utilities do not provide the exact value you need, use square bracket notation:
```html
Exact width
Calculated height
Exact hex color
Exact font size
Custom grid template
Exact positioning
Clamped padding
Arbitrary CSS property
Set a custom property
Direct child paragraphs
Supports query
Custom media query
```
Underscores in arbitrary values are treated as spaces:
```html
Background image
Grid columns: 1fr auto 1fr
```
To use an actual underscore, escape it with a backslash:
```html
Literal underscore in value
```
### 4.12 The `@apply` Directive
The `@apply` directive lets you use utility classes inside your CSS:
```css
.btn {
@apply px-4 py-2 rounded-lg font-semibold text-sm transition-colors;
}
.btn-primary {
@apply btn bg-blue-500 text-white hover:bg-blue-700;
}
.btn-secondary {
@apply btn bg-gray-200 text-gray-800 hover:bg-gray-300;
}
```
```css
/* Card component */
.card {
@apply bg-white rounded-xl shadow-md p-6 border border-gray-100;
}
.card-title {
@apply text-xl font-semibold text-gray-900 mb-2;
}
.card-body {
@apply text-gray-600 leading-relaxed;
}
```
#### `@apply` Limitations
- Cannot use `@apply` inside `@keyframes` blocks. Attempting to do so produces: `You cannot use @apply inside @keyframes.`
- If you reference a utility that does not exist, you get: `Cannot apply unknown utility class '{candidate}'`
- If your project uses a prefix and you forget it: `Cannot apply unprefixed utility class '{candidate}'. Did you mean '{prefix}:{candidate}'?`
- Circular references produce: `Cannot apply utility class '{candidate}' because it creates a circular dependency.`
> [!NOTE]
> While `@apply` is useful for extracting repeated patterns, Tailwind's recommended approach is to use component abstractions in your framework (React components, Vue components, partials, etc.) rather than creating CSS classes with `@apply`. Reserve `@apply` for cases where you cannot use component abstractions, such as styling third-party markup or CMS content.
### 4.13 Custom Utilities with `@utility`
Define entirely new utility classes:
```css
@utility content-auto {
content-visibility: auto;
}
@utility scrollbar-hidden {
scrollbar-width: none;
&::-webkit-scrollbar {
display: none;
}
}
@utility text-balance {
text-wrap: balance;
}
```
These become available as regular utility classes:
```html
Lazy-rendered content
No visible scrollbar
Balanced headline text
```
Custom utilities support variants:
```html
Variant-aware custom utility
```
#### Functional Utilities with Values
```css
@utility tab-size-* {
tab-size: --value(--tab-size-*);
}
```
This generates `tab-size-2`, `tab-size-4`, `tab-size-8`, etc., from your theme.
### 4.14 Custom Variants with `@variant`
Define new variants for conditional styling.
#### Selector-Based Variant
```css
@variant pointer-coarse (@media (pointer: coarse));
@variant pointer-fine (@media (pointer: fine));
```
Usage:
```html
```
#### Complex Selector Variants
```css
@variant hocus (&:hover, &:focus);
```
```html
```
### 4.15 Transition and Animation
```html
Scale and shadow on hover
75ms
100ms
150ms (default)
200ms
300ms
500ms
700ms
1000ms
150ms delay
Linear
Ease in
Ease out
Ease in-out
Spinning
Pinging
Pulsing
Bouncing
```
### 4.16 Transforms
```html
95% scale
105% on hover
Different X/Y scale
45 degrees
-12 degrees
Rotate on hover
Move right 1rem
Move up 0.5rem
Move down on hover
Skew X 3 degrees
Skew Y 6 degrees
Rotate from top-left corner
Scale from center
```
### 4.17 Filters and Effects
```html
Slight blur
Medium blur
Large blur
No blur
Frosted glass effect
Darkened backdrop
50% opacity
Invisible (but in DOM)
Fade in on hover
Multiply blend
Screen blend
Overlay blend
```
### 4.18 Overflow and Scroll
```html
Auto scrollbar when needed
Hidden overflow
Always show scrollbar
Horizontal scroll when needed
Vertical scroll when needed
Visible overflow
Clip overflow (no scroll)
Smooth scrolling
Slide 1
Slide 2
Slide 3
16rem scroll padding-top
4 scroll margin-top
Contain overscroll
No overscroll
```
### 4.19 Interactivity
```html
Pointer cursor
Not-allowed cursor
Wait cursor
Grab cursor
Move cursor
Text cursor
Default cursor
Click-through
Normal pointer events
Cannot be selected
Can be selected
Select all on click
Disable touch gestures
Allow horizontal panning only
Allow vertical panning only
Allow pan and zoom only
Optimize for transform changes
Optimize for scroll changes
```
### 4.20 Tables
```html
Name
Status
Role
Jane Cooper
Active
Admin
John Smith
Pending
Editor
Fixed layout
Auto layout
Table caption
```
### 4.21 SVG
```html
```
### 4.22 Accessibility
```html
Screen reader text
Skip to content
High contrast border
```
---
## 5. Common Tasks
### 5.1 Building a Responsive Navigation Bar
```html
```
### 5.2 Building a Card Component
```html
Category
Card Title
Card description text that can be truncated to three lines maximum.
This action cannot be undone. All project data will be permanently removed.
```
### 5.7 Building a Sidebar Layout
```html
Dashboard
```
### 5.8 Building a Notification / Toast
```html
Successfully saved!
Your changes have been saved.
Error occurred
Something went wrong. Please try again.
Warning
Your trial expires in 3 days.
Information
A new version is available.
```
### 5.9 Building a Badge / Tag System
```html
Badge
Active
Error
Pending
Draft
Ring Badge
Online
React
```
### 5.10 Building a Responsive Footer
```html
```
### 5.11 Building an Avatar Group
```html
+5
```
### 5.12 Building a Breadcrumb
```html
```
### 5.13 Building a Skeleton Loader
```html
```
### 5.20 Building a Glassmorphism Card
```html
Glassmorphism
A frosted glass effect achieved with backdrop-blur and semi-transparent backgrounds.
```
### 5.21 Responsive Image Gallery
```html
```
### 5.22 Aspect Ratio
```html
```
### 5.23 Extracting Components with `@apply`
When the same pattern repeats across many pages and you cannot use a framework component abstraction:
```css
@import 'tailwindcss';
/* Button components */
.btn {
@apply inline-flex items-center justify-center px-4 py-2 text-sm font-semibold rounded-lg transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed;
}
.btn-primary {
@apply btn bg-blue-600 text-white hover:bg-blue-700 focus-visible:ring-blue-500;
}
.btn-secondary {
@apply btn bg-gray-100 text-gray-700 hover:bg-gray-200 focus-visible:ring-gray-500;
}
.btn-danger {
@apply btn bg-red-600 text-white hover:bg-red-700 focus-visible:ring-red-500;
}
.btn-ghost {
@apply btn text-gray-600 hover:bg-gray-100 focus-visible:ring-gray-500;
}
/* Input component */
.input {
@apply w-full px-3 py-2 border border-gray-300 rounded-lg shadow-sm text-sm placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500;
}
.input-error {
@apply input border-red-500 focus:ring-red-500 focus:border-red-500;
}
```
### 5.24 Production Builds
#### Minification
All integration methods support minified output for production:
**Vite**: Minification happens automatically in `vite build`.
**PostCSS**: Minification is handled by your build tool (Vite, Webpack, etc.).
**CLI**: Use the `--minify` flag:
```bash
npx @tailwindcss/cli -i src/app.css -o dist/output.css --minify
```
#### What Gets Removed
Tailwind CSS only includes the CSS for utility classes it detects in your source files. If a class like `bg-purple-500` appears nowhere in your scanned files, it will not be in the output. This is automatic and requires no configuration.
#### Safelist Patterns
If you generate class names dynamically (e.g., `bg-${color}-500`), Tailwind cannot detect them at build time. Use explicit class names instead:
```html
```
Or ensure the full class names appear somewhere in your source (even in a comment or unused variable) so the scanner detects them.
### 5.25 Upgrading from Tailwind CSS v3
The `@tailwindcss/upgrade` tool automates migration from v3 to v4.
#### Running the Upgrade
```bash
npx @tailwindcss/upgrade
```
This tool:
- Converts `tailwind.config.js` to CSS-first `@theme` configuration
- Updates `@tailwind base/components/utilities` to `@import 'tailwindcss'`
- Migrates PostCSS configuration
- Updates template files with renamed utilities
- Converts plugin references to `@plugin` directives
> [!WARNING]
> Always commit your code before running the upgrade tool. Review all changes it makes. The tool handles most cases automatically, but complex configurations or custom plugin setups may need manual adjustment.
#### What the Upgrade Tool Converts
| v3 Pattern | v4 Equivalent |
|---|---|
| `tailwind.config.js` theme | `@theme { ... }` in CSS |
| `@tailwind base` | `@import 'tailwindcss/preflight'` |
| `@tailwind components` | (removed, use `@layer`) |
| `@tailwind utilities` | `@import 'tailwindcss/utilities'` |
| `content: [...]` in config | `@source` directives in CSS |
| `require('plugin')` in config | `@plugin 'plugin'` in CSS |
| `theme.extend.colors` | `@theme { --color-*: ... }` |
#### Common Manual Steps After Upgrade
1. Review `@theme` output for correctness
2. Check that `@source` paths cover all your template files
3. Verify custom plugin compatibility with v4
4. Test dark mode behavior (v4 uses `prefers-color-scheme` by default)
5. Check for renamed or removed utility classes
### 5.26 Using Tailwind with TypeScript Projects
Tailwind works with any file that contains class strings. For TypeScript projects, ensure your `@source` patterns include `.ts` and `.tsx` files:
```css
@import 'tailwindcss';
/* TypeScript files are scanned by default if in the project directory */
/* Add explicit sources if they're outside the default scan path */
@source '../src/**/*.tsx';
@source '../src/**/*.ts';
```
### 5.27 Using Tailwind with Markdown/MDX Content
For content sites that use Markdown or MDX:
```css
@import 'tailwindcss';
@source '../content/**/*.md';
@source '../content/**/*.mdx';
```
The `@tailwindcss/typography` plugin provides beautiful default styling for rendered Markdown:
```css
@import 'tailwindcss';
@plugin '@tailwindcss/typography';
```
```html
```
### 5.28 Using Tailwind with CSS Modules
Tailwind works alongside CSS Modules. Use `@reference` to access theme tokens without duplicating output:
```css
/* component.module.css */
@reference '../app.css';
.wrapper {
@apply flex items-center gap-4 p-6;
}
.title {
@apply text-xl font-bold text-gray-900;
}
```
### 5.29 Controlling Specificity with `@layer`
While Tailwind v4 handles specificity automatically, you can use standard CSS `@layer` for custom styles:
```css
@import 'tailwindcss';
@layer base {
h1 {
@apply text-3xl font-bold;
}
h2 {
@apply text-2xl font-semibold;
}
}
```
Base layer styles have lower specificity than utility classes, so utilities always win when applied via the `class` attribute.
### 5.30 Using Custom Fonts
```css
@import 'tailwindcss';
/* Import the font */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
@theme {
--font-family-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
}
```
Or with local font files:
```css
@import 'tailwindcss';
@font-face {
font-family: 'CalSans';
src: url('/fonts/CalSans-SemiBold.woff2') format('woff2');
font-weight: 600;
font-display: swap;
}
@theme {
--font-family-display: 'CalSans', sans-serif;
}
```
Use in HTML:
```html
Custom Display Font
Inter body text
```
---
## 6. Troubleshooting
### 6.1 Build and Compilation Errors
#### Error: `Cannot find module '../lightningcss.linux-x64-musl.node'`
**Cause:** The native Lightning CSS binary for your platform is missing. This commonly occurs in Alpine Linux Docker containers or musl-based environments where the glibc binary was installed instead. (GitHub issue #17958)
**Solution:**
1. Ensure you are running a clean install:
```bash
rm -rf node_modules package-lock.json
npm install
```
2. If using Alpine Linux, ensure the musl variant is available:
```bash
npm install lightningcss-linux-x64-musl
```
3. If using Docker, make sure `npm install` runs inside the container (not on the host), so the correct platform binaries are resolved.
**Prevention:** Run `npm install` in the same OS/architecture as your build environment.
---
#### Error: `Tailwind CSS is not installed`
**Cause:** The `@tailwindcss/upgrade` tool cannot find a Tailwind CSS installation in the project.
**Solution:**
1. Install Tailwind CSS first:
```bash
npm install tailwindcss
```
2. Then run the upgrade tool:
```bash
npx @tailwindcss/upgrade
```
---
#### Error: `Could not resolve '{id}' from '{base}'`
**Cause:** An `@import`, `@plugin`, or `@config` directive references a module or file that cannot be found relative to the CSS file or in `node_modules`.
**Solution:**
1. Verify the import path is correct and the file exists.
2. For npm packages, ensure they are installed: `npm install `.
3. Check that the path is relative to the CSS file containing the directive, not your project root.
---
#### Error: `The browser build does not support @import for "{id}"`
**Cause:** You are using `@import` to include an external CSS file while using the `@tailwindcss/browser` build. The browser build compiles inline CSS only.
**Solution:** The browser build does not support importing external files. Either:
- Switch to a build tool (Vite, PostCSS, CLI) for full `@import` support.
- Inline all your CSS in `
+5
