Tailwind CSS Core Patterns

# Overview

Tailwind CSS is a CSS framework that minimizes writing separate CSS files and lets you style quickly by applying utility classes and the like right in your HTML markup.
It also lets you handle other styling, such as responsive design, dark mode, and hover states, inside your HTML.
This is especially useful in frameworks like React, where you modularize CSS into separate files or use CSS-in-JS libraries such as Emotion or styled-components.
You can of course use Tailwind CSS in Vue and Svelte too, but since they let you include and modularize CSS in single-file components (SFC) such as *.vue and *.svelte without any extra library, it may be relatively less useful there.

Also, unlike typical CSS frameworks such as Bootstrap, Tailwind CSS doesn't provide predefined styled components by default.
Instead, you build the design you want by combining small utility classes directly in your HTML.
This way, only the styles you use end up in the final build, which reduces the bundle size even further.

In the following example, the two elements use an inline style and utility classes, and both produce the same result.

1
2
<div style={{ height: '100px', width: '100px', backgroundColor: 'red' }}></div>
<div className="h-[100px] w-[100px] bg-[red]"></div>

Tailwind CSS also provides predefined class values to help you write optimized styles.
However, these values are less intuitive, and you need to learn their patterns to use them effectively.
So this post analyzes and introduces the main patterns you will use most often.

1
2
<div style={{ height: '100px', width: '100px', backgroundColor: 'red' }}></div>
<div className="h-25 w-25 bg-red-500"></div>

Tailwind CSS makes it easy to handle state-based styles with something called variants.

First, with plain inline styles you can't handle a hover effect, so you have to write separate CSS like the .box class definition below.

1
2
3
4
5
6
7
8
.box {
  width: 100px;
  height: 100px;
  background-color: red;
}
.box:hover {
  background-color: blue;
}

With Tailwind CSS, however, you can handle the hover effect easily with the hover: variant.
In the following example, the bg-blue-500 utility class is applied only in the hover state.

1
2
<div className="box"></div>
<div className="h-25 w-25 bg-red-500 hover:bg-blue-500"></div>

If you need to reuse styles, you can abstract them with the @utility directive as follows.
As in the example below, you can write properties and values, or use utility classes with the @apply directive.

1
2
3
4
5
6
7
8
9
10
11
@utility box1 {
  width: 100px;
  height: 100px;
  background-color: red;
  &:hover {
    background-color: blue;
  }
}
@utility box2 {
  @apply w-25 h-25 bg-red-500 hover:bg-blue-500;
}

1
2
<div className="box1"></div>
<div className="box2"></div>

# Installation and setup

# VS Code extensions

There are several Tailwind CSS extensions you can use in VS Code.

# Tailwind CSS IntelliSense

Tailwind CSS IntelliSense is the official extension, offering features such as autocomplete, syntax highlighting, and linting.

Tailwind CSS IntelliSense

When you type part of a class, it autocompletes a list of matching utility classes.
You can pick the class you want from the list and apply it easily.

Class autocomplete

When you hover over an applied utility class, it shows the CSS that actually gets applied.
This makes it easy to understand styles that are already written.

Class preview

# Tailwind Docs

Tailwind Docs lets you search the Tailwind CSS documentation easily.
In VS Code, open the Command Palette (Cmd or Ctrl + Shift + P) and type tailwind <search term>.

Tailwind Docs

In the search results, select the style you want to apply to see how to use its utility classes right away.
The documentation page opens inside VS Code instead of a separate browser.

Searching the docs from the Command Palette

# Vite

In a Vite project, install and set up Tailwind CSS as follows.
If you don't use Prettier, skip installing prettier-plugin-tailwindcss.

1
npm i -D tailwindcss @tailwindcss/vite prettier-plugin-tailwindcss

1
2
3
4
5
6
7
8
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), tailwindcss()]
})

Set up Tailwind CSS in the global stylesheet connected to /src/main.tsx as follows.
Earlier versions used the @tailwind directive, but starting with v4, you use the CSS @import rule.

1
2
3
4
/* @tailwind base;
@tailwind components;
@tailwind utilities; */
@import "tailwindcss";

If you use Prettier, register the plugin as follows.

1
2
3
4
5
{
  "semi": false,
  "singleQuote": true,
  "plugins": ["prettier-plugin-tailwindcss"]
}

# Removing non-standard rule warnings

When you use Tailwind CSS directives such as @theme and @apply, your CSS or SCSS files may show warnings.

Warnings for non-standard rules

If you use the Tailwind CSS IntelliSense extension in VS Code, you can remove the warnings by adding the following to your settings.json file.

1
2
3
4
5
6
{
  "files.associations": {
    "*.css": "tailwindcss",
    "*.scss": "tailwindcss"
  }
}

• https://github.com/tailwindlabs/tailwindcss/discussions/5258#discussioncomment-4309415
• https://github.com/tailwindlabs/tailwindcss/discussions/5258#discussioncomment-12273733

# Next

When you create a new project with the latest Next, you don't need to set up Tailwind CSS separately if you choose the option to use it.
For an existing Next project, see Starting with the new Tailwind CSS v4 in a Next.js project.

1
2
3
4
5
6
7
8
npx create-next-app@latest <project-name>
    ✔ Would you like to use TypeScript? … Yes  # Use TypeScript?
    ✔ Would you like to use ESLint? … Yes  # Use ESLint?
    ✔ Would you like to use Tailwind CSS? … Yes  # Use Tailwind CSS?
    ✔ Would you like your code inside a `src/` directory? … No  # Use the src/ directory?
    ✔ Would you like to use App Router? (recommended) … Yes  # Use the App Router?
    ✔ Would you like to use Turbopack for next dev? … No  # Use Turbopack?
    ✔ Would you like to customize the import alias (@/* by default)? … No  # Use a path alias other than `@/*`?

If you use Prettier, install and register the plugin as follows, just like in the Vite setup.
Removing non-standard rule warnings works the same way, so see the Vite setup described earlier.

1
npm i -D prettier-plugin-tailwindcss

1
2
3
4
5
{
  "semi": false,
  "singleQuote": true,
  "plugins": ["prettier-plugin-tailwindcss"]
}

# Utility classes

A Tailwind CSS utility class is a small CSS class that holds one or more CSS properties and values, and it lets you apply CSS properties easily.

# Understanding the common patterns

Most utility classes map directly to a single CSS property, such as w-* for width and m-* for margin, but some classes combine several properties, like size-*, which combines width and height.
On top of that, the naming patterns aren't consistent: the flex-basis property uses the basis-* class, but the flex-wrap property uses the flex-* class. The usage patterns vary too: the number in the px-2 class is multiplied by the base spacing (--spacing), but the number in the border-1 class is applied in px. So there is a bit of a learning curve.
To make this easier to understand, I've summarized the common patterns of utility classes.
Once you understand the common patterns, check out the table of properties and utility classes.

# Basic usage

The most common pattern combines a CSS property prefix and that property's CSS value with a dash (-).
For example, you take the CSS float: left; property and value and join them as is to write the float-left class.
For the box-sizing: border-box; property and value, you have to shorten the property name to box-*, as in the box-border class.

Also, the abbreviations aren't consistent (width becomes w-*, text-indent becomes indent-*, and border-radius becomes rounded-*), so be careful when using them.
Be careful not to write an invalid class, such as text-indent-1 instead of indent-1.

1
<div className="float-left box-border w-10 rounded-sm indent-1"></div>

# Special values

There is also a pattern that combines a property prefix with special values such as predefined keywords, numbers, and ratios.
For example, you write the aspect-ratio: 16/9; property and value as a class with a ratio, aspect-16/9, or with a keyword, aspect-video, and you write width: 100%; as the w-full class.

Some classes, like columns-*, accept a size name as the value, as in columns-md.
There are five basic size names (xs, sm, md, lg, xl), and you can put a number of 2 or higher in front of the smallest (xs) or largest (xl) size to express even smaller or larger values, such as 3xs, 2xs, 6xl, and 7xl.

Also, for some CSS properties that accept negative values, you can add a minus sign (-) in front of the class.
For example, you write order: -1; as the -order-1 class.

1
<div className="-order-1 -m-4 aspect-square columns-md"></div>

# Value-only classes

There is a pattern that uses only the value as the class, without a property prefix.
For example, you write the display: block property and value as the block class, not display-block.

1
<span className="visible absolute block"></span>

# Using variables

You can add parentheses (()) to the property prefix to specify a variable without the var() function.
For example, you can write the width: var(--size); property and value as the w-(--size) class.

You can define a local variable like [--size:200px], using the arbitrary values approach covered in the next topic.

1
<div className="h-[calc(var(--size)+50px)] w-(--size) [--size:200px]"></div>

# Arbitrary values

You can add square brackets ([]) to the property prefix to specify an arbitrary value that isn't predefined.
For example, you can write the width: 123px; property and value as the w-[123px] class.

You can also use CSS functions, as in w-[calc(100%-40px)].
Note that whitespace (such as spaces) in the middle, as in 100% - 40px, is not allowed.

In addition, you can write a property and value as is inside [].
You can use this freely, for example to declare a local variable or to apply a property that Tailwind CSS doesn't support.

1
<div className="h-[calc(var(--size)+50px)] w-[var(--size)] [--size:200px]"></div>

1
<input className="[width:200px] text-[#ff0000] [-webkit-text-security:circle]" />

# Colors

Tailwind CSS includes a color palette by default.
You write classes with the PREFIX-COLOR-SHADE pattern, like bg-red-500 and text-blue-300.

Tailwind CSS color palette

There are 22 color names you can use, from Red to Stone.
For shades, there are 9 basic steps from 100 to 900 in increments of 100, plus the lightest 50 and the darkest 950, for a total of 11.
The idea is that 500 in the middle is the base color, and you lower the number for a lighter color or raise it for a darker one.
White and black have no shades, so you write them as bg-white and border-black.

If you want to make a color transparent, add an opacity from 0 to 100 at the end of the class, like bg-red-500/70 or bg-black/15.
Note that 100 is fully opaque and 0 is fully transparent.

1
2
3
<div className="size-[100px] border-2 border-blue-700/90 bg-red-500/50 text-pink-50">
  Colors
</div>

Also, every utility class that applies a color can additionally use the *-inherit, *-current, and *-transparent classes.
They let you inherit the parent's color (inherit), explicitly use the current color (currentColor), or make it transparent (transparent).

1
2
3
<div className="bg-inherit"> background-color: inherit; </div>
<div className="accent-current"> accent-color: currentColor; </div>
<div className="border-transparent"> border-color: transparent; </div>

# Properties and utility classes table

Based on the common patterns we just looked at, here is a list of each property and its utility classes.
Press Cmd or Ctrl + F in your browser to search, and you can find a property or class name more easily.
For details, you can select a CSS property name to go to the matching Tailwind CSS documentation.

In each table, (Variable) shows whether you can use a CSS variable, like w-(--size).
[Arbitrary] shows whether you can specify an arbitrary value, like w-[100px].

# Layout

# Flex & grid

# Spacing

space-* means the margin between elements, and you apply it to the parent element, not to the target elements.
The following example adds 8px (0.5rem) of margin between each <li>.
No margin is added above the first <li> or below the last <li>.

1
2
3
4
5
<ul className="space-y-2">
  <li>Apple</li>
  <li>Banana</li>
  <li>Cherry</li>
</ul>

Margin between elements

# Sizing

# Fonts & text

When you set the font size with a text-* class, you can also set the line height (line-height) by adding a /.

1
2
<div className="text-sm">font-size: 14px;</div>
<div className="text-sm/6">font-size: 14px; line-height: 1.5;</div>

The CSS content property can be used in the ::before and ::after pseudo-element selectors, so you use content-* classes with the before: and after: variants.
When you write text as the value, you must use _ instead of spaces, and conversely, to use an actual _, you need to escape it.
Note that inside the url() function, you don't need to escape it.

1
2
3
<div className="before:content-['Have_a_great_day!']">Have a great day!</div>
<div className="before:content-['Have\_a\_great\_day!']">Have_a_great_day!</div>
<div className="before:content-[url('https://www.heropy.dev/images/profile_m.jpg')]">HEROPY</div>

# Backgrounds

To set a gradient on an element's background, you can use the from-*, via-*, and to-* classes to set the colors of the start, middle, and end points.
The gradient in the following example starts with red on the left, passes through yellow, and ends with blue on the right.

1
<div className="h-20 w-full bg-linear-to-r from-red-500 via-yellow-500 to-blue-500"></div>

from-red-500 via-yellow-500 to-blue-500

The from-*, via-*, and to-* classes can set not only the color of each point but also its stop position.
In the following example, red stops at 10%, yellow at 30%, and blue at 50%, and the colors in between blend naturally.

1
<div className="h-20 w-full bg-linear-to-r from-red-500 from-10% via-yellow-500 via-30% to-blue-500 to-50%"></div>

from-10% via-30% to-50%

Note that in CSS, an element's background color uses the background-color property, but a background gradient has to use the background-image property.

# Borders

divide-* means the line (border) between elements, and you apply it to the parent element, not to the target elements.
The following example adds a line between each <li>.
No line appears above the first <li> or below the last <li>.

1
2
3
4
5
<ul className="divide-y-2">
  <li>Apple</li>
  <li>Banana</li>
  <li>Cherry</li>
</ul>

Lines between elements

# Effects

# Filters

# Tables

# Transitions & animation

You can create your own animation utility classes by defining --animate-* theme variables inside the @theme directive.
This is useful for defining an animation you'll reuse many times.

1
2
3
4
5
6
7
8
9
10
11
@theme {
  --animate-my-animation: my-keyframes 1s infinite alternate;
  @keyframes my-keyframes {
    0% {
      transform: translateX(0);
    }
    100% {
      transform: translateX(100px);
    }
  }
}

1
<div className="animate-my-animation"></div>

# Transforms

# Interactivity

# SVG

# Accessibility

# Variants

Every Tailwind CSS utility class can be applied conditionally through variants.
A typical example is the hover: variant, which applies styles when you hover over an element.
In the following example, the blue background is applied only on hover.

1
<div className="size-25 bg-red-500 hover:bg-blue-500"></div>

You can also nest variants.
In the following example, the first <div> contains a <span>, so the blue background is applied on hover, but the second <div> has no <span>, so the blue background is not applied even when you hover over it.

1
2
3
4
<div className="size-25 bg-red-500 hover:has-[span]:bg-blue-500">
  <span>1</span>
</div>
<div className="size-25 bg-red-500 hover:has-[span]:bg-blue-500">2</div>

# Understanding the main variants

# Dark mode

Many operating systems, such as Windows and macOS, let you choose light or dark mode, and the choice is automatically applied to the browser as well.
You can detect dark mode with the prefers-color-scheme feature of the CSS @media rule.

1
2
3
4
5
6
7
@media (prefers-color-scheme: dark) {
  html {
    color-scheme: dark;
    background-color: oklch(0.13 0.028 261.692); /* bg-gray-900 */
    color: #fff;
  }
}

With Tailwind CSS, you only need to specify which styles to use in dark mode with the dark: variant.

1
<input className="border-1 border-gray-300 dark:border-gray-600" />

If you want to control dark mode manually instead of automatically, you can use the @custom-variant directive as follows.
The dark: variant then works when an element has the dark class itself or is a descendant of such an element.

1
2
3
@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));

Now add the dark class manually.
To control the whole document, you usually add it to <html>.

1
2
3
4
<!doctype html>
<html lang="ko" class="dark">
  <!-- ... -->
</html>

Adding the dark class doesn't automatically apply dark mode styles.
If there are styles you want, you have to write them yourself.

1
2
3
4
5
html.dark {
  color-scheme: dark;
  background-color: oklch(0.13 0.028 261.692); /* bg-gray-900 */
  color: #fff;
}

# Media queries

Tailwind CSS provides five breakpoints from sm to 2xl, and besides the usual mobile-first breakpoints, it also provides the opposite, a desktop-first system.
For desktop-first development, you use the max-* variants.

Let's look at a simple example to make this clear.
In the following example, the element's background color is red when the viewport width is 767px or less, and blue when it is 768px or more (md:).

1
<div className="size-25 bg-red-500 md:bg-blue-500"></div>

In the following example, the element's background color is blue when the viewport width is 767px or less (max-md:), and red when it is 768px or more.

1
<div className="size-25 bg-red-500 max-md:bg-blue-500"></div>

You can also nest variants to specify a breakpoint range.
In the following example, the element's background color is red by default, and blue when the viewport width is 768px or more and 1279px or less.

1
<div className="size-25 bg-red-500 md:max-xl:bg-blue-500"></div>

If you want to define your own breakpoints, change the default --breakpoint-* theme variables in the Tailwind CSS @theme directive.
The following example uses the breakpoints from Bootstrap.

1
2
3
4
5
6
7
@theme {
  --breakpoint-sm: 576px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 992px;
  --breakpoint-xl: 1200px;
  --breakpoint-2xl: 1400px;
}

# Container queries

Container queries follow a pattern similar to the media queries we just looked at.
They provide 13 breakpoints from 3xs to 7xl, you can use the max-* variants, and you can also specify ranges.
However, unlike media queries, which are based on the viewport, container queries require you to mark the reference ancestor element with the @container class and put an @ in front of the variant you use.

In the following example, the background color of the third <div> is blue when the first <div>, which has the @container class, is 3xl (768px) wide or wider, and red when it is 767px wide or narrower.

1
2
3
4
5
<div className="@container max-w-[1000px] border-2">
  <div>
    <div className="size-25 bg-red-500 @3xl:bg-blue-500"></div>
  </div>
</div>

If the default container query breakpoints such as 3xs don't fit a particular situation, you can also use an arbitrary value like @min-[768px].
The following example produces the same result as the previous one.

1
2
3
4
5
<div className="@container max-w-[1000px] border-2">
  <div>
    <div className="size-25 bg-red-500 @min-[768px]:bg-blue-500"></div>
  </div>
</div>

# Styling descendant (child) elements

In most cases, you write utility classes directly on the element itself, but sometimes you may need to write styles on an ancestor element.
In that case, you can style child elements with the *: variant and descendant elements with the **: variant.
In the following example, the classes on <ul> add padding to each <li> and a text color to each <a> that has an href attribute.
So <a>Apple</a> doesn't get the text color.

1
2
3
4
5
6
7
8
9
10
11
<ul className="*:p-2 **:[a[href]]:text-red-400">
  <li>
    <a>Apple</a>
  </li>
  <li>
    <a href="#">Banana</a>
  </li>
  <li>
    <a href="#">Cherry</a>
  </li>
</ul>

If you want to style a descendant element based on the state of an ancestor element, you can use the group-*: variant.
First, add the group class to the ancestor element to mark it as the target.
Then, on the descendant element, use the group-*: variant to write the utility classes that apply based on the ancestor's state (a selector, utility class, variant, and so on).

Each <p> in the following example is shown only when you hover over its <li> or when the <li> has the active class.
So Answer B is shown right away, and Answer A is shown on hover.

1
2
3
4
5
6
7
8
9
10
11
12
13
<section>
  <h2>Frequently asked questions</h2>
  <ul>
    <li className="group">
      <h4>Question A</h4>
      <p className="invisible group-[.active]:visible group-hover:visible">Answer A</p>
    </li>
    <li className="group active">
      <h4>Question B</h4>
      <p className="invisible group-[.active]:visible  group-hover:visible">Answer B</p>
    </li>
  </ul>
</section>

# Styling sibling elements

You can also apply styles based on the state of a sibling element.
First, add the peer class to the sibling element to mark it as the target.
Then use the peer-*: variant to write the utility classes that apply based on the sibling's state.

In the following example, <p> is shown on the screen depending on whether the email in <input> is valid.
Note that the invalid: variant is the same as the CSS :invalid pseudo-class.

1
2
3
4
5
6
7
8
9
<label>
  <input
    type="email"
    className="peer"
  />
  <p className="invisible text-red-500 peer-invalid:visible">
    Please enter a valid email address.
  </p>
</label>

# Variants and CSS table

Now that you understand what variants are, take a quick look at the following table to see which variants exist and which CSS each one matches.
You don't need to remember all of them!
When you need details, select a variant name to go to the matching Tailwind CSS documentation.

# Directives

Directives are special Tailwind CSS rules that you use in CSS, not in HTML.
Let's look at the main directives you'll use often.

# @theme

You can redefine the default theme variables that Tailwind CSS uses, such as fonts, colors, and breakpoints, or create new theme variables.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@theme {
  /* Modify default theme variables */
  --font-sans: 'Pretendard', sans-serif; /* ui-sans-serif, system-ui, ... */
  --color-white: #e9e9e9; /* #fff */
  --color-black: #1a1a1a; /* #000 */
  --spacing: 10px; /* 0.25rem */
  --radius-md: 10px; /* 0.375rem */
  --breakpoint-md: 800px; /* 768px */
  --breakpoint-lg: 1100px; /* 1024px */
  --breakpoint-xl: 1400px; /* 1280px */

  /* Create custom theme variables */
  --color-my-highlight: #e96900;
}

1
<div className="bg-(--color-my-highlight)"</div>

The namespaces of theme variables you can redefine are as follows.

# @utility

You can define your own utility classes with the @utility directive.

1
2
3
4
5
@utility heropy-box-300 {
  width: 300px;
  height: 300px;
  border-radius: 10px;
}

1
<div className="heropy-box-300"></div>

You can also define more complex utility classes.
When you pass a plain number without a unit, you can use the number or integer type in the --value() function.
There are a few more types you can use this way, such as percentage and ratio, but they are hard to recommend because they aren't intuitive, behave differently depending on the property, and don't handle every value.

1
2
3
4
5
@utility heropy-box-* {
  width: --value(number)px;
  height: --value(number)px;
  border-radius: 10px;
}

1
2
3
<div className="heropy-box-100"></div>
<div className="heropy-box-300"></div>
<div className="heropy-box-500"></div>

So if you're creating a utility class that accepts many kinds of values, I recommend the arbitrary value approach with [].
With a wildcard character, you can assign any value to the --value() function.

1
2
3
4
5
@utility heropy-box-* {
  width: --value([*]);
  height: --value([*]);
  border-radius: 10px;
}

1
2
3
<div className="heropy-box-[300px]"></div>
<div className="heropy-box-[50%]"></div>
<div className="heropy-box-[10dvw]"></div>

For colors, specify the --color-* theme variable.
Then you can use the many colors that Tailwind CSS provides.

1
2
3
4
5
6
@utility heropy-box-color-* {
  width: 100px;
  height: 100px;
  border-radius: 10px;
  background-color: --value(--color-*);
}

1
2
<div className="heropy-box-color-red-500"></div>
<div className="heropy-box-color-blue-400"></div>

Along with the --value() function, you can also use the --modifier() function.
This lets you handle an extra value written with /, like text-sm/6 or bg-red-500/70.

1
2
3
4
5
6
7
@utility heropy-box-color-* {
  width: 100px;
  height: 100px;
  border-radius: 10px;
  background-color: --value(--color-*);
  opacity: --modifier(number);
}

1
2
<div className="heropy-box-color-red-500"></div>
<div className="heropy-box-color-blue-400/0.5"></div>

# @apply

The @apply directive lets you use utility classes in CSS.

The following example defines a new utility class by writing CSS properties and values directly, without @apply.

1
2
3
4
5
@utility heropy-flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

The following example produces the same result as the previous one, but uses utility classes instead of CSS properties.
If you're familiar with utility classes, this may be more convenient.

1
2
3
@utility heropy-flex-center {
  @apply flex items-center justify-center;
}

1
<div className="heropy-flex-center"></div>

# @variant

You can use the @variant directive to add variants to a utility class.
The following example defines the hover style for elements that have a heropy-box-* class.

1
2
3
4
5
6
7
8
9
@utility heropy-box-* {
  width: --value([*]);
  height: --value([*]);
  border-radius: 10px;
  transition: transform 0.3s;
  @variant hover {
    transform: scale(1.1);
  }
}

You can also rewrite the previous example with the @apply directive as follows.

1
2
3
4
5
6
@utility heropy-box-* {
  @apply size-[--value([*])] rounded-[10px] transition duration-300;
  @variant hover {
    @apply scale-[1.1];
  }
}

1
<div className="heropy-box-[300px]"></div>

You can also nest the @variant directive multiple times.
In the following example, the background color (bg-blue-100) is applied only when you hover over a focused element.

1
2
3
4
5
6
7
8
9
@utility heropy-input {
  @apply rounded-[10px] transition duration-300;
  @variant focus {
    @apply border-blue-400;
    @variant hover {
      @apply bg-blue-100;
    }
  }
}

1
<input className="heropy-input" />

# @custom-variant

You can also create your own variants with the @custom-variant directive.
Here, I created a state-open: variant that checks whether the data-state HTML attribute of an ancestor element is open.

1
@custom-variant state-open '[data-state="open"] &';

When the data-state attribute of the first <div> is open, the background color of the second <div> becomes blue.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { useState } from 'react'

export default function () {
  const [isActive, setIsActive] = useState(false)

  return (
    <>
      <div
        data-state={isActive ? 'open' : 'close'}
        onClick={() => setIsActive(!isActive)}>
        <div className="state-open:bg-blue-500"></div>
      </div>
    </>
  )
}

# More usage patterns

# Using a prefix

If utility classes conflict with classes that already exist in your project, or if you want to mark utility classes clearly, you can use the prefix option as follows.

1
@import "tailwindcss" prefix(tw);

Now you must always add the tw: prefix to utility classes.

1
<div className="tw:h-25 tw:w-25 tw:bg-red-500"></div>

# Priority

If you need to force a utility class to apply in a special situation, add ! to the end of its name to apply !important.
In the following example, the h-50 class takes priority.

1
<div className="h-50! h-100"></div>

# Applying dynamic styles

Tailwind CSS scans your project for utility classes and generates the CSS you need based on the classes you actually use.
So you shouldn't build classes dynamically.

For example, say you want to make an element whose width grows every time the count state increases. If you write the utility class so that it's built dynamically, like w-[${width}px] in the following example, the style won't be applied.

1
2
3
4
5
6
7
8
9
10
11
12
13
import { useState } from 'react'

export default function () {
  const [width, setWidth] = useState(100)

  return (
    <div
      className={`w-[${width}px] rounded-md bg-blue-500 p-3 font-bold text-white transition duration-300`}
      onClick={() => setWidth(width + 20)}>
      {width}px
    </div>
  )
}

So you need a separate style binding as follows.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { useState } from 'react'

export default function () {
  const [width, setWidth] = useState(100)

  return (
    <div
      className={`rounded-md bg-blue-500 p-3 font-bold text-white transition duration-300`}
      style={{ width: `${width}px` }}
      onClick={() => setWidth(width + 20)}>
      {width}px
    </div>
  )
}

Instead of binding an inline style for every piece of dynamic data, you can also predefine utility classes and apply them when needed, as in the following example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
export default function Button({
  color,
  children
}: {
  color: 'primary' | 'secondary' | 'error'
  children: React.ReactNode
}) {
  const colors = {
    primary: 'bg-blue-500 hover:bg-blue-600 text-white',
    secondary: 'bg-gray-400 hover:bg-gray-500 text-black',
    error: 'bg-red-500 hover:bg-red-600 text-white'
  }
  return (
    <button
      className={`${colors[color]} cursor-pointer rounded-md px-3 py-2 transition duration-200`}>
      {children}
    </button>
  )
}

To make styles more reusable and easier to maintain, you can also organize utility classes with the CVA (Class Variance Authority) library.

1
npm i class-variance-authority

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { cva, type VariantProps } from 'class-variance-authority'

const buttonStyles = cva(
  'cursor-pointer rounded-md px-3 py-2 transition duration-200',
  {
    variants: {
      color: {
        primary: 'bg-blue-500 hover:bg-blue-600 text-white',
        secondary: 'bg-gray-400 hover:bg-gray-500 text-black',
        error: 'bg-red-500 hover:bg-red-600 text-white'
      }
    },
    defaultVariants: {
      color: 'primary'
    }
  }
)

export default function Button({
  color,
  children
}: {
  color?: VariantProps<typeof buttonStyles>['color']
  children: React.ReactNode
}) {
  return <button className={buttonStyles({ color })}>{children}</button>
}

The utility classes you write in the cva function are plain JS strings, so autocomplete and preview don't work.
If you want to use the features of the Tailwind CSS IntelliSense extension in the cva or cx function, you can configure it as follows.

1
2
3
4
5
6
{
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(((?:[^()]|\\([^()]*\\))*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cx\\(((?:[^()]|\\([^()]*\\))*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

Using color swatches, autocomplete, preview, and more for utility classes in the cva function

# Merging styles

When you use Tailwind CSS and conflicting utility classes are applied to a single element, it's hard to tell which class will take priority, and the style you want may not be applied.
In the following example, the isActive state is true, but the styles of the w-25 and bg-blue-500 classes aren't applied to the element.
That's because the w-75 and bg-red-500 classes take priority.

Note that in this situation, priority is decided by declaration order, not specificity, and that order can change at any time with the Tailwind CSS build, so trying to learn the pattern is pointless.
So how should you solve this?

1
2
3
4
5
6
7
8
9
10
import { useState } from 'react'

export default function App() {
  const [isActive] = useState(true)
  return (
    <>
      <div className={`h-25 w-75 bg-red-500 ${isActive && 'w-25 bg-blue-500'}`}></div>
    </>
  )
}

This is where you can use the tailwind-merge library to solve the problem.
First, install the library.

1
npm i tailwind-merge

The library's twMerge() function makes the class applied later take priority.
You can list all the classes in a single argument as in the first <div>, but code formatting may change the order of the classes.
So if you split them into multiple arguments in order, as in the second <div>, you can set the priority more clearly and safely.
Now the styles of the w-25 and bg-blue-500 classes are applied according to the isActive state.

1
2
// The higher the number, the higher the priority!
twMerge('priority1', 'priority2', 'priority3')

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { useState } from 'react'
import { twMerge } from 'tailwind-merge'

export default function App() {
  const [isActive] = useState(true)
  return (
    <>
      <div
        className={twMerge(
          `h-25 w-75 bg-red-500 ${isActive && 'w-25 bg-blue-500'}`
        )}></div>
      <div
        className={twMerge(
          `h-25 w-75 bg-red-500`,
          isActive && 'w-25 bg-blue-500'
        )}></div>
    </>
  )
}

Sometimes you may just need to combine utility classes regardless of priority.
Since you're already using tailwind-merge, try the twJoin() function instead of clsx.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { useState } from 'react'
import { twJoin } from 'tailwind-merge'

export default function App() {
  const [isActive] = useState(true)
  const colorRed = 'bg-red-500'
  return (
    <>
      <div
        className={twJoin(
          ['h-25 w-25'],
          colorRed,
          isActive && 'bg-blue-500',
          ['w-75']
        )}></div>
      {/* ⬇️ They are combined like this. */}
      <div className="h-25 w-25 w-75 bg-blue-500 bg-red-500"></div>
    </>
  )
}