Adding New Utilities

Extending Tailwind with your own custom utility classes.

Although Tailwind provides a pretty comprehensive set of utility classes out of the box, you may run into situations where you need to add a few of your own.

Deciding on the best way to extend a framework can be paralyzing, so here are some best practices to help you add your own utilities in the most idiomatic way possible.

Using CSS

The easiest way to add your own utilities to Tailwind is to simply add them to your CSS.

Adding New Utilities - 图1Add any custom utilities to the end of your CSS file

  1. @tailwind base;
  2. @tailwind components;
  3. @tailwind utilities;
  5. .rotate-0 {
  6.   transform: rotate(0deg);
  7. }
  8. .rotate-90 {
  9.   transform: rotate(90deg);
  10. }
  11. .rotate-180 {
  12.   transform: rotate(180deg);
  13. }
  14. .rotate-270 {
  15.   transform: rotate(270deg);
  16. }

Since declaration order is important in CSS, always make sure you are adding new utilities to the end of your CSS file to avoid specificity issues.

Adding New Utilities - 图2Don’t add custom utilities to the beginning of your CSS file

  1. /* Adding utilities to the beginning of your CSS can cause specificity issues */
  2. .rotate-0 {
  3.   transform: rotate(0deg);
  4. }
  5. .rotate-90 {
  6.   transform: rotate(90deg);
  7. }
  8. .rotate-180 {
  9.   transform: rotate(180deg);
  10. }
  11. .rotate-270 {
  12.   transform: rotate(270deg);
  13. }
  15. @tailwind base;
  16. @tailwind components;
  17. @tailwind utilities;

If you’re using postcss-import or a preprocessor like Less, Sass, or Stylus, consider keeping your utilities in a separate file and importing them:

  1. /* Using postcss-import */
  2. @import "tailwindcss/base";
  3. @import "tailwindcss/components";
  4. @import "tailwindcss/utilities";
  5. @import "./custom-utilities.css";
  7. /* Using Sass or Less */
  8. @tailwind base;
  9. @tailwind components;
  10. @tailwind utilities;
  11. @import "./custom-utilities";

Generating responsive variants

If you’d like to create responsive variants of your own utilities based on the breakpoints defined in your tailwind.config.js file, wrap your utilities in the @responsive directive:

  1. @tailwind base;
  2. @tailwind components;
  3. @tailwind utilities;
  5. @responsive {
  6.   .rotate-0 {
  7.     transform: rotate(0deg);
  8.   }
  9.   .rotate-90 {
  10.     transform: rotate(90deg);
  11.   }
  12.   .rotate-180 {
  13.     transform: rotate(180deg);
  14.   }
  15.   .rotate-270 {
  16.     transform: rotate(270deg);
  17.   }
  18. }

Tailwind will automatically generate prefixed versions of each custom utility that you can use to conditionally apply those styles at different breakpoints:

  1. <!-- Rotate 180 degrees by default, but remove that rotation on medium screens and up -->
  2. <div class="rotate-180 md:rotate-0"></div>

Learn more about responsive utilities in the responsive design documentation.

Generating pseudo-class variants

If you’d like to create pseudo-class variants of your own utilities, wrap your utilities in the @variants directive:

  1. @tailwind base;
  2. @tailwind components;
  3. @tailwind utilities;
  5. @variants hover, focus {
  6.   .rotate-0 {
  7.     transform: rotate(0deg);
  8.   }
  9.   .rotate-90 {
  10.     transform: rotate(90deg);
  11.   }
  12.   .rotate-180 {
  13.     transform: rotate(180deg);
  14.   }
  15.   .rotate-270 {
  16.     transform: rotate(270deg);
  17.   }
  18. }

Tailwind will automatically generate prefixed versions of each custom utility that you can use to conditionally apply those styles at different states:

  1. <div class="rotate-0 hover:rotate-90"></div>

Pseudo-class variants are generated in the same order you list them in the @variants directive, so if you’d like one pseudo-class to take precedence over another, make sure you list that one last:

  1. /* Focus will take precedence over hover */
  2. @variants hover, focus {
  3.   .rotate-0 {
  4.     transform: rotate(0deg);
  5.   }
  6.   /* ... */
  7. }
  9. /* Hover will take precedence over focus */
  10. @variants focus, hover {
  11.   .rotate-0 {
  12.     transform: rotate(0deg);
  13.   }
  14.   /* ... */
  15. }

If you’d like to generate both responsive and pseudo-class variants of your custom utilities, wrap @variants with @responsive:

  1. @tailwind base;
  2. @tailwind components;
  3. @tailwind utilities;
  5. @responsive {
  6.   @variants hover, focus {
  7.     .rotate-0 {
  8.       transform: rotate(0deg);
  9.     }
  10.     .rotate-90 {
  11.       transform: rotate(90deg);
  12.     }
  13.     .rotate-180 {
  14.       transform: rotate(180deg);
  15.     }
  16.     .rotate-270 {
  17.       transform: rotate(270deg);
  18.     }
  19.   }
  20. }

Learn more about pseudo-class variants utilities in the pseudo-class variant documentation.

Using a plugin

In addition to adding new utility classes directly in your CSS files, you can also add utilities to Tailwind by writing your own plugin:

  1. // tailwind.config.js
  2. module.exports = {
  3.   plugins: [
  4.     function({ addUtilities }) {
  5.       const newUtilities = {
  6.         '.rotate-0': {
  7.           transform: 'rotate(0deg)',
  8.         },
  9.         '.rotate-90': {
  10.           transform: 'rotate(90deg)',
  11.         },
  12.         '.rotate-180': {
  13.           transform: 'rotate(180deg)',
  14.         },
  15.         '.rotate-270': {
  16.           transform: 'rotate(270deg)',
  17.         },
  18.       }
  20.       addUtilities(newUtilities, ['responsive', 'hover'])
  21.     }
  22.   ]
  23. }

This can be a good choice if you want to publish your custom utilities as a library or make it easier to share them across multiple projects.

Learn more in the utility plugin documentation.