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
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.
InstallationSection titled Installation
Quick InstallSection titled Quick Install
astro add command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren’t sure which package manager you’re using, run the first command.) Then, follow the prompts, and type “y” in the terminal (meaning “yes”) for each one.
If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.
Manual InstallSection titled Manual Install
First, install the
tailwindcss packages using your package manager. If you’re using npm or aren’t sure, run this in the terminal:
Then, apply this integration to your
astro.config.* file using the
UsageSection 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!
ConfigurationSection titled Configuration
Configuring TailwindSection titled Configuring Tailwind
If you used the Quick Install instructions and said yes to each prompt, you’ll see a
tailwind.config.cjs 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) 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 IntegrationSection 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.
config.pathSection titled config.path
If you want to use a different Tailwind configuration file instead of the default
tailwind.config.(js|cjs|mjs), specify that file’s location using this integration’s
config.path option. If
config.path is relative, it will be resolved relative to the root.
config.applyBaseStylesSection titled config.applyBaseStyles
By default, the integration imports a basic
base.css file on every page of your project. This basic CSS file includes the three main
To disable this default behavior, set
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.
You can now import your own
base.css as a local stylesheet.
ExamplesSection 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, and Creek themes use Tailwind for styling
- Browse Astro Tailwind projects on GitHub for more examples!
TroubleshootingSection titled Troubleshooting
Class does not exist with 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.
text-special class does not exist. If
text-special is a custom class, make sure it is defined within a
Instead of using
@layer directives in a global stylesheet, define your custom styles by adding a plugin to your Tailwind config to fix it:
Class-based modifiers do not work with 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:
OthersSection 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.
ContributingSection titled Contributing
This package is maintained by Astro’s Core team. You’re welcome to submit an issue or PR!
ChangelogSection titled Changelog
See CHANGELOG.md for a history of changes to this integration.