Functions & Directives

A reference for the custom functions and directives Tailwind exposes to your CSS.

@tailwind

Use the @tailwind directive to insert Tailwind’s base, components, utilities and screens styles into your CSS.

/**
 * This injects Tailwind's base styles and any base styles registered by
 * plugins.
 */
@tailwind base;
/**
 * This injects Tailwind's component classes and any component classes
 * registered by plugins.
 */
@tailwind components;
/**
 * This injects Tailwind's utility classes and any utility classes registered
 * by plugins.
 */
@tailwind utilities;
/**
 * Use this directive to control where Tailwind injects the responsive
 * variations of each utility.
 *
 * If omitted, Tailwind will append these classes to the very end of
 * your stylesheet by default.
 */
@tailwind screens;

@apply

Use @apply to inline any existing utility classes into your own custom CSS.

This is useful when you find a common utility pattern in your HTML that you’d like to extract to a new component.

.btn {
  @apply font-bold py-2 px-4 rounded;
}
.btn-blue {
  @apply bg-blue-500 hover:bg-blue-700 text-white;
}

Note that classes are applied based on their location in your original CSS, not based on the order you list them after the @apply directive. This is to ensure that the behavior you get when extracting a list of classes with @apply matches how those classes behave when listed directly in your HTML.

/* Input */
.btn {
  @apply py-2 p-4;
}
/* Output */
.btn {
  padding: 1rem;
  padding-top: 0.5rem;
  padding-bottom: 0.5rem;
}

If you want fine-grained control over the order in which classes are applied, use multiple @apply statements:

/* Input */
.btn {
  @apply py-2;
  @apply p-4;
}
/* Output */
.btn {
  padding-top: 0.5rem;
  padding-bottom: 0.5rem;
  padding: 1rem;
}

You can also mix @apply declarations with normal CSS declarations:

/* Input */
.btn {
  transform: translateY(-1px);
  @apply bg-black;
}
/* Output */
.btn {
  background-color: #000;
  transform: translateY(-1px);
}

Any rules inlined with @apply will have !important removed by default to avoid specificity issues:

/* Input */
.foo {
  color: blue !important;
}
.bar {
  @apply foo;
}
/* Output */
.foo {
  color: blue !important;
}
.bar {
  color: blue;
}

If you’d like to @apply an existing class and make it !important, simply add !important to the end of the declaration:

/* Input */
.btn {
  @apply font-bold py-2 px-4 rounded !important;
}
/* Output */
.btn {
  font-weight: 700 !important;
  padding-top: .5rem !important;
  padding-bottom: .5rem !important;
  padding-right: 1rem !important;
  padding-left: 1rem !important;
  border-radius: .25rem !important;
}

Note that if you’re using Sass/SCSS, you’ll need to use Sass’ interpolation feature to get this to work:

.btn {
  @apply font-bold py-2 px-4 rounded #{!important};
}

@layer

Use the @layer directive to tell Tailwind which “bucket” a set of custom styles belong to. Valid layers are a base, components, and utilities.

@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
  h1 {
    @apply text-2xl;
  }
  h2 {
    @apply text-xl;
  }
}
@layer components {
  .btn-blue {
    @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded;
  }
}
@layer utilities {
  @variants hover, focus {
    .filter-none {
      filter: none;
    }
    .filter-grayscale {
      filter: grayscale(100%);
    }
  }
}

Tailwind will automatically move any CSS within a @layer directive to the same place as the corresponding @tailwind rule, so you don’t have to worry as much about authoring your CSS in a specific order to avoid specificity issues.

Wrapping any custom CSS in a @layer directive also tells Tailwind to consider those styles for purging when purging that layer. Read our documentation on optimizing for production for more details.

@variants

You can generate responsive, hover, focus, active, and other variants of your own utilities by wrapping their definitions in the @variants directive.

@variants focus, hover {
  .rotate-0 {
    transform: rotate(0deg);
  }
  .rotate-90 {
    transform: rotate(90deg);
  }
}

This will generate the following CSS:

.rotate-0 {
  transform: rotate(0deg);
}
.rotate-90 {
  transform: rotate(90deg);
}
.focus\:rotate-0:focus {
  transform: rotate(0deg);
}
.focus\:rotate-90:focus {
  transform: rotate(90deg);
}
.hover\:rotate-0:hover {
  transform: rotate(0deg);
}
.hover\:rotate-90:hover {
  transform: rotate(90deg);
}

It’s important to note that variants are generated in the order you specify them.

So if you want focus utilities to take priority over hover utilities for example, make sure focus comes after hover in the list:

/* Input */
@variants hover, focus {
  .banana {
    color: yellow;
  }
}
/* Output */
.banana {
  color: yellow;
}
.hover\:banana:hover {
  color: yellow;
}
.focus\:banana:focus {
  color: yellow;
}

The @variants at-rule supports all of the values that are supported in the variants section of your config file, as well as any custom variants added through plugins.

@responsive

You can generate responsive variants of your own classes by wrapping their definitions in the @responsive directive:

@responsive {
  .bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
}

This is a shortcut for writing out @variants responsive { ... } which works as well.

Using the default breakpoints, this would generate these classes:

.bg-gradient-brand {
  background-image: linear-gradient(blue, green);
}
/* ... */
@media (min-width: 640px) {
  .sm\:bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
  /* ... */
}
@media  (min-width: 768px) {
  .md\:bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
  /* ... */
}
@media (min-width: 1024px) {
  .lg\:bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
  /* ... */
}
@media (min-width: 1280px) {
  .xl\:bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
  /* ... */
}

The responsive variants will be added to Tailwind’s existing media queries at the end of your stylesheet. This makes sure that classes with a responsive prefix always defeat non-responsive classes that are targeting the same CSS property.

@screen

The @screen directive allows you to create media queries that reference your breakpoints by name instead of duplicating their values in your own CSS.

For example, say you have a sm breakpoint at 640px and you need to write some custom CSS that references this breakpoint.

Instead of writing a raw media query that duplicates that value like this:

@media (min-width: 640px) {
  /* ... */
}

…you can use the @screen directive and reference the breakpoint by name:

@screen sm {
  /* ... */
}

screen()

The screen function accepts a screen name like md and generates the corresponding media feature expression:

/* Input */
@media screen(sm) {
  /* ... */
}
/* Output */
@media (min-width: 640px) {
  /* ... */
}

This can be useful when you using Tailwind with other CSS tooling that handles the @screen directive poorly. For example postcss-nesting doesn’t understand @screen but understands @media, so using @media alongside the screen() function behaves more correctly.

theme()

Use the theme() function to access your Tailwind config values using dot notation.

This can be a useful alternative to @apply when you want to reference a value from your theme configuration for only part of a declaration:

.content-area {
  height: calc(100vh - theme('spacing.12'));
}

If you need to access a value that contains a dot (like the 2.5 value in the spacing scale), you can use square bracket notation:

.content-area {
  height: calc(100vh - theme('spacing[2.5]'));
}

Since Tailwind uses a nested object syntax to define its default color palette, make sure to use dot notation to access the nested colors.

Don’t use the dash syntax when accessing nested color values

.btn-blue {
  background-color: theme('colors.blue-500');
}

Use dot notation to access nested color values

.btn-blue {
  background-color: theme('colors.blue.500');
}

←Adding New Utilities Configuration→

Edit this page on GitHub