Variants

Customize and extend variants for conditional styling

Variants in Tailwind CSS allow you to apply styles conditionally based on state, viewport size, or other conditions. Tailwind v4 includes a comprehensive set of built-in variants and provides APIs for creating custom ones.

Built-in Variants

Tailwind includes many variants out of the box:

Pseudo-class Variants

Interactive States

<button class="hover:bg-blue-600 focus:ring-2 active:scale-95">
  Interactive button
</button>

Pseudo-element Variants

<p class="first-line:uppercase first-letter:text-7xl">
  Styled text
</p>

<div class="before:content-['→'] after:content-['←']">
  Content with pseudo-elements
</div>

<input class="placeholder:italic placeholder:text-gray-400" placeholder="Search..." />

Media Query Variants

Responsive

<div class="text-sm md:text-base lg:text-lg">
  Responsive text
</div>

Variant Categories

State Variants

hover · pseudo-class

Applied on hover (with @media (hover: hover) wrapper)

<button class="hover:bg-blue-600">Hover me</button>

focus · pseudo-class

Applied when element has focus

<input class="focus:ring-2 focus:ring-blue-500" />

active · pseudo-class

Applied when element is being activated

<button class="active:scale-95">Press me</button>

visited · pseudo-class

Applied to visited links

<a class="visited:text-purple-600">Link</a>

disabled · pseudo-class

Applied when element is disabled

<button class="disabled:opacity-50" disabled>Disabled</button>

Form Variants

<!-- Validation states -->
<input class="valid:border-green-500 invalid:border-red-500" />

<!-- Checked states -->
<input type="checkbox" class="checked:bg-blue-600" />

<!-- Indeterminate state -->
<input type="checkbox" class="indeterminate:bg-gray-600" />

<!-- Required/Optional -->
<input class="required:border-red-500 optional:border-gray-300" />

Positional Variants

<ul>
  <li class="first:pt-0">First item</li>
  <li class="last:pb-0">Last item</li>
  <li class="only:border-0">Only item</li>
  <li class="odd:bg-gray-100">Odd items</li>
  <li class="even:bg-white">Even items</li>
</ul>

Group & Peer Variants

Apply styles based on parent or sibling state:

Group

<div class="group">
  <img class="group-hover:opacity-75" />
  <h3 class="group-hover:text-blue-600">Title</h3>
</div>

Responsive Variants

The default breakpoints:

--breakpoint-sm: 40rem   /* 640px */
--breakpoint-md: 48rem   /* 768px */
--breakpoint-lg: 64rem   /* 1024px */
--breakpoint-xl: 80rem   /* 1280px */
--breakpoint-2xl: 96rem  /* 1536px */

Usage:

<div class="text-sm sm:text-base md:text-lg lg:text-xl">
  Responsive sizing
</div>

Custom Variants with Plugins

Create custom variants using the plugin API:

Static Variant

Add a simple static variant:

tailwind.config.ts

import type { Config } from 'tailwindcss'
import plugin from 'tailwindcss/plugin'

export default {
  plugins: [
    plugin(({ addVariant }) => {
      // Add a `third` variant
      addVariant('third', '&:nth-child(3)')
      
      // Add a `hocus` variant (hover or focus)
      addVariant('hocus', ['&:hover', '&:focus'])
      
      // Add an `optional` variant for optional form elements
      addVariant('optional', '&:optional')
      
      // Add a `supports-grid` variant
      addVariant('supports-grid', '@supports (display: grid)')
    }),
  ],
} satisfies Config

Usage:

<div class="third:bg-blue-500">Third child is blue</div>
<button class="hocus:ring-2">Hover or focus for ring</button>

Functional Variant

Create variants that accept values:

import plugin from 'tailwindcss/plugin'

export default {
  plugins: [
    plugin(({ matchVariant }) => {
      // Add an `nth` variant
      matchVariant(
        'nth',
        (value) => `&:nth-child(${value})`,
      )
      
      // Add a `data` variant with values
      matchVariant(
        'data',
        (value) => `&[data-${value}]`,
        {
          values: {
            checked: 'checked',
            active: 'active',
            disabled: 'disabled',
          },
        },
      )
    }),
  ],
}

Usage:

<div class="nth-3:bg-blue-500">Third child</div>
<div class="nth-[2n]:bg-gray-100">Even children</div>
<div class="data-active:bg-green-500" data-active>Active state</div>

Compound Variants

Create variants that modify other variants:

import plugin from 'tailwindcss/plugin'

export default {
  plugins: [
    plugin(({ addVariant }) => {
      // Add a custom group variant
      addVariant('group-optional', ':merge(.group):optional &')
      
      // Add a custom peer variant  
      addVariant('peer-optional', ':merge(.peer):optional ~ &')
    }),
  ],
}

Functional Variants

Some variants accept arbitrary values:

nth

<div class="nth-3:bg-blue-500">3rd child</div>
<div class="nth-[2n+1]:bg-gray-100">Odd children</div>

Stacking Variants

Combine multiple variants:

<!-- Responsive + hover -->
<button class="md:hover:bg-blue-600">Desktop hover</button>

<!-- Dark mode + hover + focus -->
<button class="dark:hover:focus:ring-4">Complex state</button>

<!-- Group + responsive + hover -->
<div class="group-hover:md:scale-110">Scales on group hover (desktop)</div>

Variant Order

Variants are applied in a specific order (roughly):

1. Responsive variants (sm:, md:, etc.)
2. State variants (hover:, focus:, etc.)
3. Compound variants (group-*:, peer-*:)
4. Pseudo-elements (before:, after:, etc.)

The order of variants in your class name doesn’t matter - Tailwind handles ordering automatically based on CSS specificity rules.

Advanced Variant Examples

Custom Dark Mode

Implement a custom dark mode strategy:

export default {
  darkMode: ['variant', '&:is(.dark *)'],
}

RTL Support

import plugin from 'tailwindcss/plugin'

export default {
  plugins: [
    plugin(({ addVariant }) => {
      addVariant('rtl', '&:is([dir="rtl"] *)')
      addVariant('ltr', '&:is([dir="ltr"] *)')
    }),
  ],
}

Usage:

<div class="ml-4 rtl:mr-4 rtl:ml-0">
  RTL-aware margin
</div>

Container Queries

Use container query variants:

<div class="@container">
  <div class="@md:text-lg @lg:text-xl">
    Responsive to container size
  </div>
</div>

Not Variant

Negate other variants:

<div class="not-first:mt-4">Margin except first</div>
<div class="not-last:border-b">Border except last</div>
<div class="not-hover:opacity-75">Opacity when not hovered</div>

Variant Modifiers

Some variants support modifiers:

<!-- Named group -->
<div class="group/card">
  <div class="group-hover/card:opacity-100">
    Only affected by .group/card
  </div>
</div>

<!-- Named peer -->
<input class="peer/email" type="email" />
<span class="peer-invalid/email:visible">Invalid email</span>

Best Practices

1. Use semantic variants - hover:, focus:, etc. are more maintainable than arbitrary selectors
2. Leverage responsive variants - Build mobile-first with progressive enhancement
3. Group related states - Use group and peer for parent/sibling relationships
4. Be mindful of specificity - More variants = higher specificity

Stacking too many variants can create overly specific selectors that are hard to override. Consider extracting complex variant combinations into component classes.