Quickstart Guide

Get up and running with Tailwind CSS in just a few minutes. This guide will walk you through creating a new project, installing Tailwind, and building your first component.

This guide covers Tailwind CSS v4.2.1. If you’re upgrading from v3, check out the migration guide.

Quick Start with Vite + React

The fastest way to get started with Tailwind CSS is using Vite with React. Follow these steps to create a new project from scratch.

Create a new Vite project

Use your preferred package manager to scaffold a new Vite + React project:

npm create vite@latest my-tailwind-app -- --template react
cd my-tailwind-app

Install Tailwind CSS and the Vite plugin

Install Tailwind CSS and the official Vite plugin:

npm install tailwindcss@latest @tailwindcss/vite@latest

Configure Vite

Add the Tailwind CSS plugin to your vite.config.ts or vite.config.js:

vite.config.ts

import tailwindcss from '@tailwindcss/vite'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

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

The Vite plugin automatically detects your environment and optimizes CSS in production builds.

Import Tailwind in your CSS

Create or update your main CSS file (e.g., src/index.css) to import Tailwind:

src/index.css

@import 'tailwindcss';

Then import this CSS file in your main entry point:

src/main.tsx

import React from 'react'
import ReactDOM from 'react-dom/client'
import { App } from './App'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

Start building

Run the development server and start using Tailwind’s utility classes:

npm run dev

Your project is now set up with Tailwind CSS! Continue reading to learn how to build your first component.

Building Your First Component

Let’s build a beautiful card component using Tailwind’s utility classes. This example demonstrates the power of utility-first CSS.

Simple Card Component

Here’s a complete card component with an image, title, description, and button:

src/App.tsx

export function App() {
  return (
    <div className="min-h-screen bg-gray-50 flex items-center justify-center p-4">
      <div className="max-w-sm rounded-lg overflow-hidden shadow-lg bg-white">
        <img 
          className="w-full h-48 object-cover" 
          src="https://via.placeholder.com/400x300" 
          alt="Placeholder"
        />
        <div className="p-6">
          <h2 className="text-2xl font-bold text-gray-900 mb-2">
            Card Title
          </h2>
          <p className="text-gray-600 mb-4">
            This is a simple card component built with Tailwind CSS. 
            It includes an image, title, description, and a call-to-action button.
          </p>
          <button className="bg-blue-500 hover:bg-blue-700 text-white font-semibold py-2 px-4 rounded">
            Learn More
          </button>
        </div>
      </div>
    </div>
  )
}

Understanding the Utilities

Let’s break down what each utility class does:

Layout
Card Container
Image
Typography
Button

<div className="min-h-screen bg-gray-50 flex items-center justify-center p-4">

min-h-screen - Minimum height of 100vh
bg-gray-50 - Light gray background color
flex - Display as flexbox
items-center - Center items vertically
justify-center - Center items horizontally
p-4 - Padding of 1rem (16px) on all sides

<div className="max-w-sm rounded-lg overflow-hidden shadow-lg bg-white">

max-w-sm - Maximum width of 384px
rounded-lg - Large border radius (0.5rem)
overflow-hidden - Hide content that overflows
shadow-lg - Large box shadow
bg-white - White background

<img className="w-full h-48 object-cover">

w-full - Width of 100%
h-48 - Height of 12rem (192px)
object-cover - Cover the container while maintaining aspect ratio

<h2 className="text-2xl font-bold text-gray-900 mb-2">

text-2xl - Font size of 1.5rem (24px)
font-bold - Font weight of 700
text-gray-900 - Very dark gray text
mb-2 - Margin bottom of 0.5rem (8px)

<button className="bg-blue-500 hover:bg-blue-700 text-white font-semibold py-2 px-4 rounded">

bg-blue-500 - Blue background
hover:bg-blue-700 - Darker blue on hover
text-white - White text color
font-semibold - Font weight of 600
py-2 - Vertical padding of 0.5rem
px-4 - Horizontal padding of 1rem
rounded - Border radius of 0.25rem

Responsive Design

Make your card responsive across different screen sizes using Tailwind’s breakpoint system:

export function ResponsiveCard() {
  return (
    <div className="min-h-screen bg-gray-50 flex items-center justify-center p-4">
      {/* Card adapts from full width on mobile to fixed width on larger screens */}
      <div className="w-full md:max-w-md lg:max-w-lg rounded-lg overflow-hidden shadow-lg bg-white">
        <img 
          className="w-full h-48 md:h-56 lg:h-64 object-cover" 
          src="https://via.placeholder.com/400x300" 
          alt="Placeholder"
        />
        <div className="p-4 md:p-6">
          {/* Text size increases on larger screens */}
          <h2 className="text-xl md:text-2xl lg:text-3xl font-bold text-gray-900 mb-2">
            Responsive Card
          </h2>
          <p className="text-sm md:text-base text-gray-600 mb-4">
            This card adjusts its size and typography based on screen width.
          </p>
          <button className="w-full md:w-auto bg-blue-500 hover:bg-blue-700 text-white font-semibold py-2 px-4 rounded">
            Learn More
          </button>
        </div>
      </div>
    </div>
  )
}

Tailwind uses a mobile-first approach. Unprefixed utilities apply to all screen sizes, while prefixed utilities (like md: and lg:) apply at the specified breakpoint and above.

Breakpoint Reference

Prefix	Min Width	Typical Device
`sm:`	640px	Large phones
`md:`	768px	Tablets
`lg:`	1024px	Laptops
`xl:`	1280px	Desktops
`2xl:`	1536px	Large desktops

Hover, Focus, and Other States

Tailwind makes it easy to style interactive states using variant prefixes:

export function InteractiveButton() {
  return (
    <div className="flex gap-4 p-8">
      {/* Hover effects */}
      <button className="bg-blue-500 hover:bg-blue-700 hover:scale-105 text-white font-semibold py-2 px-4 rounded transition">
        Hover Me
      </button>
      
      {/* Focus effects */}
      <button className="bg-green-500 focus:ring-4 focus:ring-green-300 focus:outline-none text-white font-semibold py-2 px-4 rounded">
        Focus Me
      </button>
      
      {/* Active state */}
      <button className="bg-purple-500 active:bg-purple-800 text-white font-semibold py-2 px-4 rounded">
        Click Me
      </button>
      
      {/* Disabled state */}
      <button className="bg-gray-500 disabled:opacity-50 disabled:cursor-not-allowed text-white font-semibold py-2 px-4 rounded" disabled>
        Disabled
      </button>
    </div>
  )
}

Common State Variants

hover: - Style on mouse hover
focus: - Style when element has focus
active: - Style when element is being clicked
disabled: - Style when element is disabled
group-hover: - Style based on parent hover state
dark: - Style in dark mode

Add the transition utility to enable smooth animations between states.

Common Utility Patterns

Here are some frequently used utility combinations:

<div className="container mx-auto px-4">
  <!-- Content is centered with horizontal padding -->
</div>

Quick Start with Next.js

If you prefer Next.js, here’s how to set up Tailwind CSS:

Create a Next.js project

npx create-next-app@latest my-tailwind-app
cd my-tailwind-app

Install dependencies

npm install tailwindcss@latest @tailwindcss/postcss@latest

Configure PostCSS

Create a postcss.config.js file in your project root:

postcss.config.js

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Import Tailwind CSS

Add Tailwind to your global CSS file (e.g., app/globals.css):

app/globals.css

@import 'tailwindcss';

Start building

npm run dev

You’re ready to use Tailwind utilities in your Next.js components!

Customizing Your Setup

Adding Custom Colors

Define custom colors using CSS variables in your main CSS file:

src/index.css

@import 'tailwindcss';

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
  --color-accent: #f59e0b;
}

Now use them in your components:

<div className="bg-primary text-white">
  Custom primary color
</div>

Creating Reusable Components

Use @layer to add custom component styles:

src/index.css

@import 'tailwindcss';

@layer components {
  .btn {
    @apply px-4 py-2 rounded font-semibold;
  }
  
  .btn-primary {
    @apply bg-blue-500 hover:bg-blue-700 text-white;
  }
  
  .btn-secondary {
    @apply bg-gray-500 hover:bg-gray-700 text-white;
  }
}

Use your custom components:

<button className="btn btn-primary">
  Primary Button
</button>

Only extract components when you find yourself repeating the exact same utility combinations many times. Don’t prematurely abstract - embrace the utility-first approach first.

Production Optimization

Tailwind CSS v4 automatically optimizes your CSS for production. Here are some tips to maximize performance:

1. Enable Minification

The Vite plugin automatically minifies in production, but you can configure it:

vite.config.ts

import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    tailwindcss({
      // Optimization is enabled by default in production
      optimize: true,
    }),
  ],
})

2. Limit Source Scanning

Use the @source directive to limit which files Tailwind scans:

src/index.css

@import 'tailwindcss';

@source "../src/**/*.{js,jsx,ts,tsx}";

3. Remove Unused Styles

Tailwind v4 uses the Oxide engine to automatically detect and remove unused CSS. Just ensure your build process is set up correctly.

Tailwind CSS v4’s Rust-powered engine provides up to 10x faster builds compared to v3, with automatic optimization in production.

4. Enable Source Maps

For debugging production issues:

vite.config.ts

export default defineConfig({
  css: {
    devSourcemap: true,
  },
  plugins: [tailwindcss()],
})

Next Steps

Now that you’ve built your first Tailwind CSS project, explore more advanced features:

Core Concepts

Deep dive into utility-first CSS and Tailwind’s philosophy

Responsive Design

Master responsive layouts with Tailwind’s breakpoint system

Dark Mode

Implement dark mode with a single class prefix

Customization

Customize your theme with colors, spacing, and more

Editor Setup

Configure IntelliSense for autocomplete and linting

Adding Custom Styles

Learn when and how to add custom CSS to your Tailwind project

Common Issues

Styles Not Applying

If your styles aren’t working:

Ensure you’ve imported Tailwind CSS in your main CSS file
Check that your CSS file is imported in your main entry point
Verify the Vite plugin is configured correctly
Restart your development server

IntelliSense Not Working

For better autocomplete:

Install the Tailwind CSS IntelliSense extension
Configure your editor following the editor setup guide

Build Performance

For faster builds:

Limit source file scanning with @source directives
Use the Oxide engine (included by default in v4)
Only optimize CSS in production builds

Need more help? Check out our installation guide for detailed setup instructions or join the Tailwind CSS Discord community.

Getting Started

Core Concepts

Customization

Build Integration

Advanced

Upgrading

Quickstart Guide

Quickstart Guide

Quick Start with Vite + React

Building Your First Component

Simple Card Component

Understanding the Utilities

Responsive Design

Breakpoint Reference

Hover, Focus, and Other States

Common State Variants

Common Utility Patterns

Quick Start with Next.js

Customizing Your Setup

Adding Custom Colors

Creating Reusable Components

Production Optimization

1. Enable Minification

2. Limit Source Scanning

3. Remove Unused Styles

4. Enable Source Maps

Next Steps

Core Concepts

Responsive Design

Dark Mode

Customization

Editor Setup

Adding Custom Styles

Common Issues

Styles Not Applying

IntelliSense Not Working

Build Performance

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Customization

Build Integration

Advanced

Upgrading

​Quickstart Guide

​Quick Start with Vite + React

​Building Your First Component

​Simple Card Component

​Understanding the Utilities

​Responsive Design

​Breakpoint Reference

​Hover, Focus, and Other States

​Common State Variants

​Common Utility Patterns

​Quick Start with Next.js

​Customizing Your Setup

​Adding Custom Colors

​Creating Reusable Components

​Production Optimization

​1. Enable Minification

​2. Limit Source Scanning

​3. Remove Unused Styles

​4. Enable Source Maps

​Next Steps

Core Concepts

Responsive Design

Dark Mode

Customization

Editor Setup

Adding Custom Styles

​Common Issues

​Styles Not Applying

​IntelliSense Not Working

​Build Performance

Build docs developers (and LLMs) love

Quickstart Guide

Quick Start with Vite + React

Building Your First Component

Simple Card Component

Understanding the Utilities

Responsive Design

Breakpoint Reference

Hover, Focus, and Other States

Common State Variants

Common Utility Patterns

Quick Start with Next.js

Customizing Your Setup

Adding Custom Colors

Creating Reusable Components

Production Optimization

1. Enable Minification

2. Limit Source Scanning

3. Remove Unused Styles

4. Enable Source Maps

Next Steps

Common Issues

Styles Not Applying

IntelliSense Not Working

Build Performance