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’
  • ‘hover’
  • ‘focus’
  • ‘active’It’s important to note that your array of variants is not merged with the defaults, so if you’d like to enable another variant for a utility, you need to repeat the default variants for that utility as well.

Variants - 图1Don’t list only the extra variants you want to enable

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

Variants - 图2Always provide the complete list of variants you want to enable

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

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', 'focus-within', 'hover', 'focus', 'active']

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-black > * { background-color: #000; }
  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 all variants

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:

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

Note that enabling all 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 visited variant (among others):

  1. // tailwind.config.js
  2. {
  3.   variants: {
  4.     backgroundColor: ['responsive', 'hover', 'focus', 'visited'],
  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.     alignContent: ['responsive'],
  6.     alignItems: ['responsive'],
  7.     alignSelf: ['responsive'],
  8.     appearance: ['responsive'],
  9.     backgroundAttachment: ['responsive'],
  10.     backgroundColor: ['responsive', 'hover', 'focus'],
  11.     backgroundPosition: ['responsive'],
  12.     backgroundRepeat: ['responsive'],
  13.     backgroundSize: ['responsive'],
  14.     borderCollapse: ['responsive'],
  15.     borderColor: ['responsive', 'hover', 'focus'],
  16.     borderRadius: ['responsive'],
  17.     borderStyle: ['responsive'],
  18.     borderWidth: ['responsive'],
  19.     boxShadow: ['responsive', 'hover', 'focus'],
  20.     cursor: ['responsive'],
  21.     display: ['responsive'],
  22.     fill: ['responsive'],
  23.     flex: ['responsive'],
  24.     flexDirection: ['responsive'],
  25.     flexGrow: ['responsive'],
  26.     flexShrink: ['responsive'],
  27.     flexWrap: ['responsive'],
  28.     float: ['responsive'],
  29.     fontFamily: ['responsive'],
  30.     fontSize: ['responsive'],
  31.     fontSmoothing: ['responsive'],
  32.     fontStyle: ['responsive'],
  33.     fontWeight: ['responsive', 'hover', 'focus'],
  34.     height: ['responsive'],
  35.     inset: ['responsive'],
  36.     justifyContent: ['responsive'],
  37.     letterSpacing: ['responsive'],
  38.     lineHeight: ['responsive'],
  39.     listStylePosition: ['responsive'],
  40.     listStyleType: ['responsive'],
  41.     margin: ['responsive'],
  42.     maxHeight: ['responsive'],
  43.     maxWidth: ['responsive'],
  44.     minHeight: ['responsive'],
  45.     minWidth: ['responsive'],
  46.     objectFit: ['responsive'],
  47.     objectPosition: ['responsive'],
  48.     opacity: ['responsive'],
  49.     order: ['responsive'],
  50.     outline: ['responsive', 'focus'],
  51.     overflow: ['responsive'],
  52.     padding: ['responsive'],
  53.     pointerEvents: ['responsive'],
  54.     position: ['responsive'],
  55.     resize: ['responsive'],
  56.     stroke: ['responsive'],
  57.     tableLayout: ['responsive'],
  58.     textAlign: ['responsive'],
  59.     textColor: ['responsive', 'hover', 'focus'],
  60.     textDecoration: ['responsive', 'hover', 'focus'],
  61.     textTransform: ['responsive'],
  62.     userSelect: ['responsive'],
  63.     verticalAlign: ['responsive'],
  64.     visibility: ['responsive'],
  65.     whitespace: ['responsive'],
  66.     width: ['responsive'],
  67.     wordBreak: ['responsive'],
  68.     zIndex: ['responsive'],
  69.   }
  70. }