@astrojs/ tailwind

This Astro integration brings Tailwind’s utility CSS classes to every .astro file and framework component in your project, along with support for the Tailwind configuration file.

Why Tailwind?

Section titled Why Tailwind?

Tailwind lets you use utility classes instead of writing CSS. These utility classes are mostly one-to-one with a certain CSS property setting: for example, adding the text-lg to an element is equivalent to setting font-size: 1.125rem in CSS. You might find it easier to write and maintain your styles using these predefined utility classes!

If you don’t like those predefined settings, you can customize the Tailwind configuration file to your project’s design requirements. For example, if the “large text” in your design is actually 2rem, you can change the lg fontSize setting to 2rem.

Tailwind is also a great choice to add styles to React, Preact, or Solid components, which don’t support a <style> tag in the component file.

Note: it’s generally discouraged to use both Tailwind and another styling method (e.g. Styled Components) in the same file.

Installation

Section titled Installation

Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

Run one of the following commands in a new terminal window.

npm

npx astro add tailwind

pnpm

pnpm astro add tailwind

Yarn

yarn astro add tailwind

If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

Manual Install

Section titled Manual Install

First, install the @astrojs/tailwind and tailwindcss packages using your package manager.

npm

npm install @astrojs/tailwind tailwindcss

pnpm

pnpm add @astrojs/tailwind tailwindcss

Yarn

yarn add @astrojs/tailwind tailwindcss

Then, apply the integration to your Astro config file file using the integrations property:

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [tailwind()],
});

Then, create a tailwind.config.mjs file in your project’s root directory. You can use the following command to generate a basic configuration file for you:

npm

npx tailwindcss init

pnpm

pnpm dlx tailwindcss init

Yarn

yarn dlx tailwindcss init

Finally, add this basic configuration to your tailwind.config.mjs file:

tailwind.config.mjs

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

Usage

Section titled Usage

When you install the integration, Tailwind’s utility classes should be ready to go right away. Head to the Tailwind docs to learn how to use Tailwind, and if you see a utility class you want to try, add it to any HTML element to your project!

Autoprefixer is also set up automatically when working in dev mode, and for production builds, so Tailwind classes will work in older browsers.

Configuration

Section titled Configuration

Configuring Tailwind

Section titled Configuring Tailwind

If you used the Quick Install instructions and said yes to each prompt, you’ll see a tailwind.config.mjs file in your project’s root directory. Use this file for your Tailwind configuration changes. You can learn how to customize Tailwind using this file in the Tailwind docs.

If it isn’t there, you add your own tailwind.config.(js|cjs|mjs|ts|mts|cts) file to the root directory and the integration will use its configurations. This can be great if you already have Tailwind configured in another project and want to bring those settings over to this one.

Configuring the Integration

Section titled Configuring the Integration

The Astro Tailwind integration handles the communication between Astro and Tailwind and it has its own options. Change these in the astro.config.mjs file (not the Tailwind configuration file) which is where your project’s integration settings live.

configFile

Section titled configFile

Previously known as config.path in @astrojs/tailwind v3. See the v4 changelog for updating your config.

If you want to use a different Tailwind configuration file instead of the default tailwind.config.(js|cjs|mjs|ts|mts|cts), specify that file’s location using this integration’s configFile option. If configFile is relative, it will be resolved relative to the current working directory.

Caution

Changing this isn’t recommended since it can cause problems with other tools that integrate with Tailwind, like the official Tailwind VSCode extension.

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // Example: Provide a custom path to a Tailwind config file
      configFile: './custom-config.mjs',
    }),
  ],
});

applyBaseStyles

Section titled applyBaseStyles

Previously known as config.applyBaseStyles in @astrojs/tailwind v3. See the v4 changelog for updating your config.

By default, the integration imports a basic base.css file on every page of your project. This basic CSS file includes the three main @tailwind directives:

base.css

/* The integration's default injected base.css file */
@tailwind base;
@tailwind components;
@tailwind utilities;

To disable this default behavior, set applyBaseStyles to false. This can be useful if you need to define your own base.css file (to include a @layer directive, for example). This can also be useful if you do not want base.css to be imported on every page of your project.

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // Example: Disable injecting a basic `base.css` import on every page.
      // Useful if you need to define and/or import your own custom `base.css`.
      applyBaseStyles: false,
    }),
  ],
});

You can now import your own base.css as a local stylesheet.

nesting

Section titled nesting

Set true to apply the tailwindcss/nesting PostCSS plugin so you can write nested CSS declarations alongside Tailwind’s syntax. This option is false by default.

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [
    tailwind({
      // Example: Allow writing nested CSS declarations
      // alongside Tailwind's syntax
      nesting: true,
    }),
  ],
});

Examples

Section titled Examples

• The Astro Tailwind Starter gets you up and running with a base for your project that uses Tailwind for styling
• Astro’s homepage uses Tailwind. Check out its Tailwind configuration file or an example component
• The Astro Ink, Sarissa Blog, Astro Tech Blog and Creek themes use Tailwind for styling
• Browse Astro Tailwind projects on GitHub for more examples!

Troubleshooting

Section titled Troubleshooting

Class does not exist with @apply directives

Section titled Class does not exist with @apply directives

When using the @apply directive in an Astro, Vue, Svelte, or another component integration’s <style> tag, it may generate errors about your custom Tailwind class not existing and cause your build to fail.

error   The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.

Instead of using @layer directives in a global stylesheet, define your custom styles by adding a plugin to your Tailwind config to fix it:

tailwind.config.mjs

export default {
  // ...
  plugins: [
    function ({ addComponents, theme }) {
      addComponents({
        '.btn': {
          padding: theme('spacing.4'),
          margin: 'auto',
        },
      });
    },
  ],
};

Class-based modifiers do not work with @apply directives

Section titled Class-based modifiers do not work with @apply directives

Certain Tailwind classes with modifiers rely on combining classes across multiple elements. For example, group-hover:text-gray compiles to .group:hover .text-gray. When this is used with the @apply directive in Astro <style> tags, the compiled styles are removed from the build output because they do not match any markup in the .astro file. The same issue may also happen in framework components that support scoped styles like Vue and Svelte.

To fix this, you can use inline classes instead:

<p class="text-black group-hover:text-gray">Astro</p>

Others

Section titled Others

• If your installation doesn’t seem to be working, try restarting the dev server.
• If you edit and save a file and don’t see your site update accordingly, try refreshing the page.
• If refreshing the page doesn’t update your preview, or if a new installation doesn’t seem to be working, then restart the dev server.

For help, check out the #support channel on Discord. Our friendly Support Squad members are here to help!

You can also check our Astro Integration Documentation for more on integrations.

More integrations

Front-end frameworks

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR adapters

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Other integrations

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind