You're looking at the documentation for Tailwind CSS v2.
Go to Tailwind CSS v3 →
Tailwind CSS home page
Tailwind CSS on GitHub

Installation

Learn how to get Tailwind CSS up and running in your project.

Integration guides

Installing Tailwind CSS can be a slightly different process depending on what other frameworks/tools you’re using, so we’ve put together a bunch of guides that cover popular setups.

Next.js
Vue 3 (Vite)
Laravel
Nuxt.js
Create React App
Gatsby

Don’t see your favorite tool in the list? We’re always working on new guides, but in the mean time you can follow the instructions for installing Tailwind CSS as a PostCSS plugin instead to get set up in no time.

Installing Tailwind CSS as a PostCSS plugin

Tailwind CSS requires Node.js 12.13.0 or higher.

For most real-world projects, we recommend installing Tailwind as a PostCSS plugin. Most modern frameworks use PostCSS under the hood already, and there’s a good chance you’ve used or are currently using other PostCSS plugins like autoprefixer.

If you’ve never heard of PostCSS or are wondering how it’s different from tools like Sass, read our guide on using PostCSS as your preprocessor for an introduction.

If this is a bit over your head and you’d like to try Tailwind without configuring PostCSS, read our instructions on using Tailwind CLI instead.

Install Tailwind via npm

For most projects (and to take advantage of Tailwind’s customization features), you’ll want to install Tailwind and its peer-dependencies via npm.

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

Since Tailwind does not automatically add vendor prefixes to the CSS it generates, we recommend installing autoprefixer to handle this for you like we’ve shown in the snippet above.

If you’re integrating Tailwind with a tool that relies on an older version of PostCSS, you may see an error like this:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

In this case, you should install the PostCSS 7 compatibility build instead.

Add Tailwind as a PostCSS plugin

Add tailwindcss and autoprefixer to your PostCSS configuration. Most of the time this is a postcss.config.js file at the root of your project, but it could also be a .postcssrc file, or postcss key in your package.json file.

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

If you aren’t sure where PostCSS plugins are configured for the tools you’re using, you’ll want to refer to the documentation for those tools to learn where this should go. A search for “configure postcss {my tool}” will get you the answer pretty fast, too.

If you’re using any other PostCSS plugins, you should read our documentation on using PostCSS as your preprocessor for more details about the best way to order them with Tailwind.

Create your configuration file

If you’d like to customize your Tailwind installation, generate a config file for your project using the Tailwind CLI utility included when you install the tailwindcss npm package:

npx tailwindcss init

This will create a minimal tailwind.config.js file at the root of your project:

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

Learn more about configuring Tailwind in the configuration documentation.

Include Tailwind in your CSS

Create a CSS file if you don’t already have one, and use the @tailwind directive to inject Tailwind’s base, components, and utilities styles:

/* ./your-css-folder/styles.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind will swap these directives out at build-time with all of the styles it generates based on your configured design system.

If you’re using postcss-import (or a tool that uses it under the hood, such as Webpacker for Rails), use our imports instead of the @tailwind directive to avoid issues when importing any of your own additional files:

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

If you’re working in a JavaScript framework like React or Vue that supports directly importing CSS files into your JS, you can also skip creating a CSS file altogether and import tailwindcss/tailwind.css instead which has all of these directives already in place:

// app.js
import "tailwindcss/tailwind.css"

Building your CSS

How you actually build your project will depend on the tools that you’re using. Your framework may include a command like npm run dev to start a development server that compiles your CSS in the background, you may be running webpack yourself, or maybe you’re using postcss-cli and running a command like postcss styles.css -o compiled.css.

If you’re already familiar with PostCSS you probably know what you need to do, if not refer to the documentation for the tool you are using.

When building for production, be sure to configure the purge option to remove any unused classes for the smallest file size:

  // tailwind.config.js
  module.exports = {
+   purge: [
+     './src/**/*.html',
+     './src/**/*.js',
+   ],
    darkMode: false, // or 'media' or 'class'
    theme: {
      extend: {},
    },
    variants: {},
    plugins: [],
  }

Read our separate guide on optimizing for production to learn more about tree-shaking unused styles for best performance.

If you’re integrating Tailwind with a tool that relies on an older version of PostCSS, you may see an error like this when trying to build your CSS:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

In this case, you should switch to our PostCSS 7 compatibility build instead.

Using Tailwind CLI

Tailwind CSS requires Node.js 12.13.0 or higher.

If you’d like to compile your CSS with Tailwind without integrating it directly into any sort of build tooling, you can use the Tailwind CLI tool to generate your CSS without configuring PostCSS or even installing Tailwind as a dependency if you don’t want to.

Use npx which is a tool that is automatically installed alongside npm to generate a fully compiled Tailwind CSS file:

npx tailwindcss -o tailwind.css

This will create a file called tailwind.css generated based on Tailwind’s default configuration, and automatically add any necessary vendor prefixes using autoprefixer.

Now you can pull this file into your HTML just like any other stylesheet:

<!doctype html>
<html>
<head>
  <!-- ... -->
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link href="/tailwind.css" rel="stylesheet">
</head>
<body>
  <!-- ... -->
</body>
</html>

Watching for changes

You can use the --watch or -w flag to start a watch process and automatically rebuild your CSS any time you make any changes:

npx tailwindcss -o tailwind.css --watch

Using a custom CSS file

If you’d like to process any custom CSS alongside the default styles Tailwind generates, create a CSS file wherever you normally would and use the @tailwind directive to include Tailwind’s base, components, and utilities styles:

/* ./src/tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .btn {
    @apply px-4 py-2 bg-blue-600 text-white rounded;
  }
}

Then include the path to that file when building your CSS:

npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

Read about adding base styles, extracting components, and adding new utilities to learn more about adding custom CSS on top of Tailwind.

Customizing your configuration

If you’d like to customize what Tailwind generates, create a tailwind.config.js file using the Tailwind CLI tool:

npx tailwindcss init

This will create a minimal tailwind.config.js file at the root of your project:

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

This file will automatically be read when building your CSS with Tailwind CLI:

npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

If you’d like to keep your config file in a different location or give it a different name, pass the config file path using the -c option when building your CSS:

npx tailwindcss -i ./src/tailwind.css -c ./.config/tailwind.config.js -o ./dist/tailwind.css

Learn more about configuring Tailwind in the configuration documentation.

Disabling Autoprefixer

By default, the Tailwind CLI tool will run your CSS through Autoprefixer to add any necessary vendor prefixes. If you already have Autoprefixer set up in your build pipeline somewhere further down the chain, you can disable it in the Tailwind CLI tool using the --no-autoprefixer flag to avoid running it twice:

npx tailwindcss --no-autoprefixer -o tailwind.css

Using a custom PostCSS configuration

If you’d like to use other PostCSS plugins alongside Tailwind, you can create a postcss.config.js file in your project root to add your extra plugins and Tailwind will include them if you use the --postcss flag when building your CSS:

npx tailwindcss --postcss -o tailwind.css
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-100vh-fix'),
  ]
}

By default, plugins are applied after Tailwind generates your CSS. If you have plugins that need to run before Tailwind, just include tailwindcss in your plugin list and Tailwind CLI will detect it and respect your custom plugin order:

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('tailwindcss'),
    require('postcss-100vh-fix'),
  ]
}

If you’d like to automatically generate a basic postcss.config.js file when creating your tailwind.config.js file, use the --postcss or -p flag when initializing your config file:

npx tailwindcss init --postcss

Building for production

When building for production, set NODE_ENV=production on the command line when building your CSS:

NODE_ENV=production npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

This will make sure Tailwind removes any unused CSS for best performance. Read our separate guide on optimizing for production to learn more.

You can also use the --minify flag to compress your CSS with cssnano:

NODE_ENV=production npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css --minify

Using Tailwind via CDN

Before using the CDN build, please note that many of the features that make Tailwind CSS great are not available without incorporating Tailwind into your build process.

  • You can't customize Tailwind's default theme
  • You can't use any directives like @apply, @variants, etc.
  • You can't enable additional variants like group-focus
  • You can't install third-party plugins
  • You can't tree-shake unused styles

To get the most out of Tailwind, you really should install it as a PostCSS plugin.

To pull in Tailwind for quick demos or just giving the framework a spin, grab the latest default configuration build via CDN:

<link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">

Note that while the CDN build is large (72.8kB compressed, 2936.0kB raw), it's not representative of the sizes you see when including Tailwind as part of your build process.

Sites that follow our best practices are almost always under 10kb compressed.

HTML starter template

For Tailwind’s styles to work as expected, you’ll want to use the HTML5 doctype and include the responsive viewport meta tag to properly handle responsive styles on all devices.

<!doctype html>
<html>
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link href="/path/to/tailwind.css" rel="stylesheet">
  <!-- ... -->
</head>
<body>
  <!-- ... -->
</body>
</html>

Many front-end frameworks like Next.js, vue-cli and others do all this for you behind the scenes automatically, so depending on what you’re building you might not need to set this up.

PostCSS 7 compatibility build

As of v2.0, Tailwind CSS depends on PostCSS 8. Because PostCSS 8 is only a few months old, many other tools in the ecosystem haven’t updated yet, which means you might see an error like this in your terminal after installing Tailwind and trying to compile your CSS:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

To help bridge the gap until everyone has updated, we also publish a PostCSS 7 compatibility build as @tailwindcss/postcss7-compat on npm.

If you run into the error mentioned above, uninstall Tailwind and re-install using the compatibility build instead:

npm uninstall tailwindcss postcss autoprefixer
npm install -D tailwindcss@npm:@tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

The compatibility build is identical to the main build in every way, so you aren’t missing out on any features or anything like that.

Once the rest of your tools have added support for PostCSS 8, you can move off of the compatibility build by re-installing Tailwind and its peer-dependencies using the latest tag:

npm uninstall tailwindcss
npm install -D tailwindcss@latest postcss@latest autoprefixer@latest
Release Notes
Edit this page on GitHub