Quickstart Guide

Get started with Tailwind CSS in minutes and build your first component with utility-first styling

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.

1. Create a new Vite project

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

   npm

   npm create vite@latest my-tailwind-app -- --template react
   cd my-tailwind-app
   
2. Install Tailwind CSS and the Vite plugin

   Install Tailwind CSS and the official Vite plugin:

   npm

   npm install tailwindcss@latest @tailwindcss/vite@latest
   
3. 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.

4. 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>,
   )
   
5. 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

<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

Card Container

<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

Image

<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

Typography

<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

<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:

Centered Container

<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:

1. Create a Next.js project

   npx create-next-app@latest my-tailwind-app
   cd my-tailwind-app
   
2. Install dependencies

   npm

   npm install tailwindcss@latest @tailwindcss/postcss@latest
   
3. Configure PostCSS

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

   postcss.config.js

   module.exports = {
     plugins: {
       '@tailwindcss/postcss': {},
     },
   }
   
4. Import Tailwind CSS

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

   app/globals.css

   @import 'tailwindcss';
   
5. 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:

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

IntelliSense Not Working

For better autocomplete:

1. Install the Tailwind CSS IntelliSense extension
2. 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.