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.

@tailwind base;
@tailwind components;
@tailwind utilities;
@layer utilities {
  .scroll-snap-none {
    scroll-snap-type: none;
  }
  .scroll-snap-x {
    scroll-snap-type: x;
  }
  .scroll-snap-y {
    scroll-snap-type: y;
  }
}

By using the @layer directive, Tailwind will automatically move those styles to the same place as @tailwind utilities to avoid unintended specificity issues.

Using the @layer directive will also instruct Tailwind to consider those styles for purging when purging the utilities layer. Read our Controlling File Size documentation for more details.

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:

@tailwind base;
@tailwind components;
@tailwind utilities;
@layer utilities {
  @responsive {
    .scroll-snap-none {
      scroll-snap-type: none;
    }
    .scroll-snap-x {
      scroll-snap-type: x;
    }
    .scroll-snap-y {
      scroll-snap-type: y;
    }
  }
}

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

<!-- Use `scroll-snap-type: none` by default, then use `scroll-snap-type: x` on medium screens and up -->
<div class="scroll-snap-none md:scroll-snap-x"></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:

@tailwind base;
@tailwind components;
@tailwind utilities;
@layer utilities {
  @variants hover, focus {
    .filter-none {
      filter: none;
    }
    .filter-grayscale {
      filter: grayscale(100%);
    }
  }
}

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

<div class="filter-grayscale hover:filter-none"></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:

/* Focus will take precedence over hover */
@variants hover, focus {
  .filter-grayscale {
    filter: grayscale(100%);
  }
  /* ... */
}
/* Hover will take precedence over focus */
@variants focus, hover {
  .filter-grayscale {
    filter: grayscale(100%);
  }
  /* ... */
}

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

@tailwind base;
@tailwind components;
@tailwind utilities;
@layer utilities {
  @responsive {
    @variants hover, focus {
      .filter-none {
        filter: none;
      }
      .filter-grayscale {
        filter: grayscale(100%);
      }
    }
  }
}

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:

// tailwind.config.js
const plugin = require('tailwindcss/plugin')
module.exports = {
  plugins: [
    plugin(function({ addUtilities }) {
      const newUtilities = {
        '.filter-none': {
          filter: 'none',
        },
        '.filter-grayscale': {
          filter: 'grayscale(100%)',
        },
      }
      addUtilities(newUtilities, ['responsive', 'hover'])
    })
  ]
}

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.

← Extracting Components   Functions & Directives →