Configuring Variants

Configuring which utility variants are enabled in your project.

Overview

The variants section of your tailwind.config.js file is where you control which core utility plugins should have responsive variants and pseudo-class variants generated.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     appearance: ['responsive'],
  5.     // ...
  6.     borderColor: ['responsive', 'hover', 'focus'],
  7.     // ...
  8.     outline: ['responsive', 'focus'],
  9.     // ...
  10.     zIndex: ['responsive'],
  11.   },
  12. }

Each property is a core plugin name pointing to an array of variants to generate for that plugin. The following variants are supported out of the box:

  • 'responsive'
  • 'group-hover'
  • 'focus-within'
  • 'first'
  • 'last'
  • 'odd'
  • 'even'
  • 'hover'
  • 'focus'
  • 'active'
  • 'visited'
  • 'disabled'
  • 'motion-safe'
  • 'motion-reduce'

Overriding default variants

Any variants you specify will *override the default variants for that plugin.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // Only 'active' variants will be generated
  5.     backgroundColor: ['active'],
  6.   },
  7. }

When overriding the default variants, make sure you always specify all the variants you’d like to enable, not just the new ones you’d like to add.

Extending default variants

If you’d like to enable extra variants for a plugin in addition to the defaults, you can configure your variants using a function instead of an array:

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // The 'active' variant will be generated in addition to the defaults
  5.     backgroundColor: ({ after }) => after(['active']),
  6.   },
  7. }

Because the order of variants is important, we provide a few helper functions as arguments that make it easy to add new variants in the right place.

before

The before helper lets you add new variants to the beginning of a plugin’s default variant list.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // Defaults are ['responsive', 'hover', 'focus']
  5.     backgroundColor: ({ before }) => before(['active']),
  6.     // Output: ['active', 'responsive', 'hover', 'focus']
  7.   },
  8. }

If you’d like to add new variants before a specific variant in the list, pass that as the second argument:

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // Defaults are ['responsive', 'hover', 'focus']
  5.     backgroundColor: ({ before }) => before(['active'], 'focus'),
  6.     // Output: ['responsive', 'hover', 'active', 'focus']
  7.   },
  8. }

after

The after helper lets you add new variants to the end of a plugin’s default variant list.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // Defaults are ['responsive', 'hover', 'focus']
  5.     backgroundColor: ({ after }) => after(['active']),
  6.     // Output: ['responsive', 'hover', 'focus', 'active']
  7.   },
  8. }

If you’d like to add new variants after a specific variant in the list, pass that as the second argument:

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // Defaults are ['responsive', 'hover', 'focus']
  5.     backgroundColor: ({ after }) => after(['active'], 'hover'),
  6.     // Output: ['responsive', 'hover', 'active', 'focus']
  7.   },
  8. }

without

The without helper lets you disable a variant that is enabled by default.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // Defaults are ['responsive', 'hover', 'focus']
  5.     backgroundColor: ({ without }) => without(['focus']),
  6.     // Output: ['responsive', 'hover']
  7.   },
  8. }

variants

The variants helper lets you retrieve the variants for a specific plugin to read from directly.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // Defaults are ['responsive', 'hover', 'focus']
  5.     backgroundColor: ({ variants }) => [...variants('backgroundColor'), 'active'],
  6.     // Output: ['responsive', 'hover', 'focus', 'active']
  7.   },
  8. }

This is an escape hatch and you probably won’t ever need it. Stick to before, after, and without — they will handle everything you actually need.

Composing multiple helpers

Each helper can optionally take a list of variants as the final argument, and if provided, will apply against that list instead of the default variant list for the current plugin.

This makes it possible to compose them together and add variants both before and after, or add a variant before another variant while removing another variant, etc.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     // Defaults are ['responsive', 'hover', 'focus']
  5.     backgroundColor: ({ before, after, without }) => without(['focus'], before(['active'], 'hover', after(['focus-within'], 'responsive'))),
  6.     // Output: [responsive', 'focus-within', 'active', 'hover']
  7.   },
  8. }

This looks complex and you probably won’t need to do this often, but the power is there if you need it.

Ordering variants

It’s important to note that variants are generated in the order you specify them, so variants at the end of the list will take precedence over variants at the beginning of the list.

In this example, focus variants have the highest precedence for backgroundColor utilities, but hover variants have the highest precedence for borderColor utilities:

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     backgroundColor: ['hover', 'focus'],
  5.     borderColor: ['focus', 'hover'],
  6.   },
  7. }
  1. /* Generated CSS */
  3. .bg-black { background-color: #000 }
  4. .bg-white { background-color: #fff }
  5. /* ... */
  7. .hover\:bg-black:hover { background-color: #000 }
  8. .hover\:bg-white:hover { background-color: #fff }
  9. /* ... */
  11. .focus\:bg-black:focus { background-color: #000 }
  12. .focus\:bg-white:focus { background-color: #fff }
  13. /* ... */
  15. .border-black { border-color: #000 }
  16. .border-white { border-color: #fff }
  17. /* ... */
  19. .focus\:border-black:focus { border-color: #000 }
  20. .focus\:border-white:focus { border-color: #fff }
  21. /* ... */
  23. .hover\:border-black:hover { border-color: #000 }
  24. .hover\:border-white:hover { border-color: #fff }
  25. /* ... */

This means that given the following HTML:

  1. <input class="focus:bg-white hover:bg-black focus:border-white hover:border-black">

…if the input was hovered and focused at the same time, the background would be white but the border would be black.

Generally, we recommend the following order for the built-in variants, although you are free to use whatever order makes the most sense for your own project:

  1. ['responsive', 'group-hover', 'group-focus', 'focus-within', 'first', 'last', 'odd', 'even', 'hover', 'focus', 'active', 'visited', 'disabled']

The responsive variant

The responsive variant is the only variant that is not impacted by the order you list in your variants configuration.

This is because the responsive variant automatically stacks with pseudo-class variants, meaning that if you specify both responsive and hover variants for a utility, Tailwind will generate responsive hover variants as well:

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     backgroundColor: ['responsive', 'hover'],
  5.     borderColor: ['responsive', 'focus'],
  6.   },
  7. }
  1. /* Generated CSS */
  3. .bg-black { background-color: #000 }
  4. /* ... */
  5. .hover\:bg-black:hover { background-color: #000 }
  6. /* ... */
  8. .border-black { border-color: #000 }
  9. /* ... */
  10. .focus\:border-black:focus { border-color: #000 }
  11. /* ... */
  14. @media (min-width: 640px) {
  15.   .sm\:bg-black { background-color: #000 }
  16.   /* ... */
  17.   .sm\:hover\:bg-black:hover { background-color: #000 }
  18.   /* ... */
  20.   .sm\:border-black { border-color: #000 }
  21.   /* ... */
  22.   .sm\:focus\:border-black:focus { border-color: #000 }
  23.   /* ... */
  24. }
  26. @media (min-width: 768px) {
  27.   .md\:bg-black { background-color: #000 }
  28.   /* ... */
  29.   .md\:hover\:bg-black:hover { background-color: #000 }
  30.   /* ... */
  32.   .md\:border-black { border-color: #000 }
  33.   /* ... */
  34.   .md\:focus\:border-black:focus { border-color: #000 }
  35.   /* ... */
  36. }
  38. @media (min-width: 1024px) {
  39.   .lg\:bg-black { background-color: #000 }
  40.   /* ... */
  41.   .lg\:hover\:bg-black:hover { background-color: #000 }
  42.   /* ... */
  44.   .lg\:border-black { border-color: #000 }
  45.   /* ... */
  46.   .lg\:focus\:border-black:focus { border-color: #000 }
  47.   /* ... */
  48. }
  50. @media (min-width: 1280px) {
  51.   .xl\:bg-black { background-color: #000 }
  52.   /* ... */
  53.   .xl\:hover\:bg-black:hover { background-color: #000 }
  54.   /* ... */
  56.   .xl\:border-black { border-color: #000 }
  57.   /* ... */
  58.   .xl\:focus\:border-black:focus { border-color: #000 }
  59.   /* ... */
  60. }

Responsive variants are grouped together and inserted at the end of your stylesheet by default to avoid specificity issues. If you’d like to customize this behavior for whatever reason, you can use the @tailwind screens directive to specify where responsive variants should be inserted.

The default variant

You can use the special default variant to control where the normal, non-prefixed versions of a utility are generated relative to the other variants.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     backgroundColor: ['hover', 'default', 'focus'],
  5.   },
  6. }
  1. /* Generated CSS */
  3. .hover\:bg-black:hover { background-color: #000 }
  4. .hover\:bg-white:hover { background-color: #fff }
  5. /* ... */
  7. .bg-black { background-color: #000 }
  8. .bg-white { background-color: #fff }
  9. /* ... */
  11. .focus\:bg-black:focus { background-color: #000 }
  12. .focus\:bg-white:focus { background-color: #fff }
  13. /* ... */

This is an advanced feature and only really useful if you have a custom variant (like children in the example below) that should have a lower precedence than the normal version of a utility.

  1. // tailwind.config.js
  2. module.exports = {
  3.   variants: {
  4.     backgroundColor: ['children', 'default', 'hover', 'focus'],
  5.   },
  6. }
  1. /* Generated CSS */
  3. .children\:bg-black > * { background-color: #000; }
  4. .children\:bg-white > * { background-color: #fff; }
  6. .bg-black { background-color: #000 }
  7. .bg-white { background-color: #fff }
  8. /* ... */
  10. .hover\:bg-black:hover { background-color: #000 }
  11. .hover\:bg-white:hover { background-color: #fff }
  12. /* ... */
  14. .focus\:bg-black:focus { background-color: #000 }
  15. .focus\:bg-white:focus { background-color: #fff }
  16. /* ... */

Learn more about creating custom variants in the variant plugin documentation.

Enabling variants globally

To specify a global set of variants that should be applied to all utilities, you can assign an array of variants directly to the variants property instead of configuring variants separately:

  1. // tailwind.config.js
  2. module.exports  = {
  3.   variants: ['responsive', 'group-hover', 'disabled', 'hover', 'focus', 'active']
  4. }

Note that enabling a lot of variants for all plugins will result in much bigger file sizes. Before you do this, be sure to read our guide on Controlling File Size.

Using custom variants

If you’ve written or installed a plugin that adds a new variant, you can enable that variant by including it in your variants configuration just like if it were a built-in variant.

For example, the tailwindcss-interaction-variants plugin adds a group-disabled variant (among others):

  1. // tailwind.config.js
  2. {
  3.   variants: {
  4.     backgroundColor: ['responsive', 'hover', 'focus', 'group-disabled'],
  5.   },
  6.   plugins: [
  7.     require('tailwindcss-interaction-variants')(),
  8.   ],
  9. }

Learn more about creating custom variants in the variant plugin documentation.

Default variants reference

Here is a complete reference of Tailwind’s default variants configuration, which can be useful when you’d like to add a new variant while preserving the defaults.

  1. // Default configuration
  2. module.exports = {
  3.   // ...
  4.   variants: {
  5.     accessibility: ['responsive', 'focus'],
  6.     alignContent: ['responsive'],
  7.     alignItems: ['responsive'],
  8.     alignSelf: ['responsive'],
  9.     appearance: ['responsive'],
  10.     backgroundAttachment: ['responsive'],
  11.     backgroundClip: ['responsive'],
  12.     backgroundColor: ['responsive', 'hover', 'focus'],
  13.     backgroundImage: ['responsive'],
  14.     gradientColorStops: ['responsive', 'hover', 'focus'],
  15.     backgroundOpacity: ['responsive', 'hover', 'focus'],
  16.     backgroundPosition: ['responsive'],
  17.     backgroundRepeat: ['responsive'],
  18.     backgroundSize: ['responsive'],
  19.     borderCollapse: ['responsive'],
  20.     borderColor: ['responsive', 'hover', 'focus'],
  21.     borderOpacity: ['responsive', 'hover', 'focus'],
  22.     borderRadius: ['responsive'],
  23.     borderStyle: ['responsive'],
  24.     borderWidth: ['responsive'],
  25.     boxShadow: ['responsive', 'hover', 'focus'],
  26.     boxSizing: ['responsive'],
  27.     container: ['responsive'],
  28.     cursor: ['responsive'],
  29.     display: ['responsive'],
  30.     divideColor: ['responsive'],
  31.     divideOpacity: ['responsive'],
  32.     divideStyle: ['responsive'],
  33.     divideWidth: ['responsive'],
  34.     fill: ['responsive'],
  35.     flex: ['responsive'],
  36.     flexDirection: ['responsive'],
  37.     flexGrow: ['responsive'],
  38.     flexShrink: ['responsive'],
  39.     flexWrap: ['responsive'],
  40.     float: ['responsive'],
  41.     clear: ['responsive'],
  42.     fontFamily: ['responsive'],
  43.     fontSize: ['responsive'],
  44.     fontSmoothing: ['responsive'],
  45.     fontVariantNumeric: ['responsive'],
  46.     fontStyle: ['responsive'],
  47.     fontWeight: ['responsive', 'hover', 'focus'],
  48.     height: ['responsive'],
  49.     inset: ['responsive'],
  50.     justifyContent: ['responsive'],
  51.     justifyItems: ['responsive'],
  52.     justifySelf: ['responsive'],
  53.     letterSpacing: ['responsive'],
  54.     lineHeight: ['responsive'],
  55.     listStylePosition: ['responsive'],
  56.     listStyleType: ['responsive'],
  57.     margin: ['responsive'],
  58.     maxHeight: ['responsive'],
  59.     maxWidth: ['responsive'],
  60.     minHeight: ['responsive'],
  61.     minWidth: ['responsive'],
  62.     objectFit: ['responsive'],
  63.     objectPosition: ['responsive'],
  64.     opacity: ['responsive', 'hover', 'focus'],
  65.     order: ['responsive'],
  66.     outline: ['responsive', 'focus'],
  67.     overflow: ['responsive'],
  68.     overscrollBehavior: ['responsive'],
  69.     padding: ['responsive'],
  70.     placeContent: ['responsive'],
  71.     placeItems: ['responsive'],
  72.     placeSelf: ['responsive'],
  73.     placeholderColor: ['responsive', 'focus'],
  74.     placeholderOpacity: ['responsive', 'focus'],
  75.     pointerEvents: ['responsive'],
  76.     position: ['responsive'],
  77.     resize: ['responsive'],
  78.     space: ['responsive'],
  79.     stroke: ['responsive'],
  80.     strokeWidth: ['responsive'],
  81.     tableLayout: ['responsive'],
  82.     textAlign: ['responsive'],
  83.     textColor: ['responsive', 'hover', 'focus'],
  84.     textOpacity: ['responsive', 'hover', 'focus'],
  85.     textDecoration: ['responsive', 'hover', 'focus'],
  86.     textTransform: ['responsive'],
  87.     userSelect: ['responsive'],
  88.     verticalAlign: ['responsive'],
  89.     visibility: ['responsive'],
  90.     whitespace: ['responsive'],
  91.     width: ['responsive'],
  92.     wordBreak: ['responsive'],
  93.     zIndex: ['responsive'],
  94.     gap: ['responsive'],
  95.     gridAutoFlow: ['responsive'],
  96.     gridTemplateColumns: ['responsive'],
  97.     gridAutoColumns: ['responsive'],
  98.     gridColumn: ['responsive'],
  99.     gridColumnStart: ['responsive'],
  100.     gridColumnEnd: ['responsive'],
  101.     gridTemplateRows: ['responsive'],
  102.     gridAutoRows: ['responsive'],
  103.     gridRow: ['responsive'],
  104.     gridRowStart: ['responsive'],
  105.     gridRowEnd: ['responsive'],
  106.     transform: ['responsive'],
  107.     transformOrigin: ['responsive'],
  108.     scale: ['responsive', 'hover', 'focus'],
  109.     rotate: ['responsive', 'hover', 'focus'],
  110.     translate: ['responsive', 'hover', 'focus'],
  111.     skew: ['responsive', 'hover', 'focus'],
  112.     transitionProperty: ['responsive'],
  113.     transitionTimingFunction: ['responsive'],
  114.     transitionDuration: ['responsive'],
  115.     transitionDelay: ['responsive'],
  116.     animation: ['responsive']
  117.   }
  118. }

← Spacing   Writing Plugins →