Tailwind CSS v2.2.0

Six weeks ago I didn't even have v2.2 on my roadmap and yet somehow here we are today, with one of the biggest Tailwind CSS feature releases of all-time?!

This release is loaded with tons of cool new stuff, mostly targeting the new Just-in-Time mode which unlocks so many cool ideas we probably couldn't have pulled off if we had to keep being mindful of the CSS file size in development.

To upgrade, install the latest version via npm:

npm install -D tailwindcss@latest

Note that we've had to make a couple small changes to the JIT engine as we've added features, fixed bugs, and improved the overall reliability, so make sure to read about the changes and deprecations when upgrading if you are using just-in-time mode.

New features
Changes and deprecations
Fixes and improvements

New features

All-new improved Tailwind CLI (#4526, #4558)

We've rewritten the Tailwind CLI tool from the ground-up with a performance-first mindset, while also adding support for a bunch of new features.

npx tailwindcss -o dist/tailwind.css --watch --jit --purge="./src/**/*.html"

Here are some of the highlights:

No installation or configuration necessary — simply npx tailwindcss -o output.css to compile Tailwind from anywhere. You can even enable JIT mode with the --jit flag and pass in your content files using the --purge option, all without creating a config file.
Watch mode — so you can automatically rebuild your CSS whenever you make any changes.
JIT performance optimizations — since our CLI is Tailwind-specific we've been able to make tons of optimizations that make it the absolute fastest build tool for compiling your CSS in JIT mode.
Minification support — now you can minify your CSS with cssnano just by adding the --minify flag.
PostCSS plugin support — the new CLI will read and respect any extra plugins you configure using a postcss.config.js file.

It's fully backwards-compatible with the previous CLI, so if you've got any scripts set up already you should be able to upgrade to v2.2 without making any changes to your scripts.

Check out our updated Tailwind CLI documentation to learn more.

Note that if you were using the tailwindcss-cli wrapper package, you can safely switch to tailwindcss as we've managed to resolve the peer-dependency issues that forced us to create the wrapper package in the first place.

Before and after pseudo-element variants (#4461)

This feature is only available in Just-in-Time mode.

People have been asking for this for years and it's finally here! We've added first-party support for styling pseudo-elements like before and after:

<div class="before:block before:bg-blue-500 after:flex after:bg-pink-300"></div>

We set content: "" automatically any time you use a before or after variant to make sure the elements are rendered, but you can override it using the new content utilities which have full arbitrary value support:

<div class="before:content-['hello'] before:block ..."></div>

You can even grab the content from an attribute using the CSS attr() function:

<div before="hello world" class="before:content-[attr(before)] before:block ..."></div>

This can be super helpful when your content has spaces in it, since spaces can't be used in CSS class names.

First-letter/line variants (#4482)

This feature is only available in Just-in-Time mode.

We've added variants for the first-letter and first-line pseudo-elements, so you can do stuff like drop caps:

<p class="first-letter:text-4xl first-letter:font-bold first-letter:float-left">
  The night was March 31, 1996, and it was finally time for Bret Hart to face off against Shawn
  Michaels in the long anticipated Iron Man match — a 60 minute war of endurance where the man who
  scored the most number of falls would walk away as the WWF World Heavyweight Champion.
</p>

Selected text variants (#4482)

This feature is only available in Just-in-Time mode.

We've added a new selection variant that makes it super easy to style highlighted to match your design:

<p class="selection:bg-pink-200">
  After nearly a grueling hour of warfare with neither man scoring a fall, Hart locked in the
  Sharpshooter, his signature submission hold. As Michaels screamed in pain, the crowd were certain
  that Hart was about to walk away from WrestleMania XII as the still-World Heavyweight Champion.
</p>

We've even built this feature in such a way that it can be applied to a parent element and cascade down, so you can set a highlight color for your whole site by applying a utility to the body:

<body class="selection:bg-pink-200">
  <!-- ... -->
  <p>
    But Michaels didn't give up — he held on until the bell rang and the designated 60 minutes was
    up. Hart walked away content, thinking that without a clear winner, the title was his to hold.
    He was not prepared for what would happen next, when Gorilla Monsoon declared the match would
    continue under sudden death rules.
  </p>
</body>

List marker variants (#4482)

This feature is only available in Just-in-Time mode.

You can use the new marker variant to style the bullets or numbers at the beginning of a list:

<h1>WrestleMania XII Results</h1>

<ol class="marker:text-gray-500 marker:font-medium">
  <li>
    The British Bulldog, Owen Hart, and Vader defeated Ahmed Johnson, Jake Roberts, and Yokozuna
  </li>
  <li>Roddy Piper defeated Goldust</li>
  <li>Stone Cold Steve Austin defeated Savio Vega</li>
  <li>The Ultimate Warrior defeated Hunter Hearst Helmsley</li>
  <li>The Undertaker defeated Diesel</li>
  <li>Shawn Michaels defeated Bret Hart</li>
</ol>

Like the selection variant, we've implemented this in a way that it cascades from the parent, so you don't have to repeat it for each list item.

Sibling selector variants (#4556)

This feature is only available in Just-in-Time mode.

Tailwind CSS v2.2 adds new peer-* variants that behave much like the group-* variants, but for targeting sibling elements instead of parent elements.

This is useful for things like styling an element when a preceding checkbox is checked, doing things like floating labels, and lots more:

<label>
  <input type="checkbox" class="peer sr-only">
  <span class="h-4 w-4 bg-gray-200 peer-checked:bg-blue-500">
  <!-- ... -->
</label>

Just like group can be combined with any other variant, peer can as well, so you have variants like peer-hover, peer-focus, peer-disabled, and loads more at your fingertips.

The generated CSS uses the general sibling combinator and looks like this:

.peer:checked ~ .peer-checked\:bg-blue-500 {
  background-color: #3b82f6;
}

So just like in vanilla CSS, it will only work for targeting previous siblings, not siblings that appear later in the DOM.

Exhaustive pseudo-class support (#4482)

This feature is only available in Just-in-Time mode.

We've added variants for basically every single missing pseudo-class we could think of in this release:

only (only-child)
first-of-type
last-of-type
only-of-type
target
default
indeterminate
placeholder-shown
autofill
required
valid
invalid
in-range
out-of-range

Personal favorite in the list is placeholder-shown — when combined with the new sibling selector variants it makes it possible to do cool stuff like floating labels:

<div class="relative">
  <input id="name" class="peer ...">
  <label for="name" class="peer-placeholder-shown:top-4 peer-focus:top-0 ...">
</div>

Shorthand color opacity syntax (#4348)

This feature is only available in Just-in-Time mode.

Instead of using utilities like bg-opacity-50, text-opacity-25, or placeholder-opacity-40, Tailwind CSS v2.2 gives you a new color opacity shorthand you can use to tweak the alpha channel of a color directly in the color utility itself:

- <div class="bg-red-500 bg-opacity-25">
+ <div class="bg-red-500/25">

This means you can now change the opacity of colors anywhere in Tailwind, even where we previously didn’t have specific opacity utilities, like in gradients for example:

<div class="bg-gradient-to-r from-red-500/50"></div>

The opacity values are taken from your opacity scale, but you can also use arbitrary opacity values using square bracket notation:

<div class="bg-red-500/[0.31]"></div>

If I'm being honest, I am more excited about never having to create another core plugin like placeholderOpacity.js for you people again than I am about actually using the feature. And I'm really excited about the feature, so that says something.

Extended arbitrary value support (#4263)

This feature is only available in Just-in-Time mode.

We've gone over every core plugin in Tailwind to try and add the most flexible arbitrary value support we possibly could, and I think we've covered pretty much everything at this point.

You should be able to whatever arbitrary values you want, just about wherever you want:

<div class="col-start-[73] placeholder-[#aabbcc] object-[50%] ..."></div>

If you find one we missed, open an issue and we'll sort it out.

In addition to making arbitrary value support more comprehensive, we've also added a new type-hint syntax to handle ambiguous situations. For example, if you are using a CSS variable as an arbitrary value, it's not always clear what the generated CSS should be:

<!-- Is this a font size utility, or a text color utility? -->
<div class="text-[var(--mystery-var)]"></div>

Now you can provide a hint to the engine by prefixing the arbitrary value with the type name:

<div class="text-[color:var(--mystery-var)]"></div>

Currently, the supported types are:

length
color
angle
list

We'll probably flesh this out even more over time as people discover new edge cases but this should get you very far.

Improved nesting support (#4318)

Since Tailwind introduces a lot of non-standard CSS at-rules like @tailwind and @apply, you can often run into weird output when combining it with a PostCSS nesting plugin like postcss-nested or postcss-nesting.

To ease the pain here, we've included a new PostCSS plugin in the tailwindcss package that acts as a lightweight compatibility layer between existing nesting plugins and Tailwind itself.

So if you need nesting support in your project, use our plugin, and stick it before Tailwind in your PostCSS plugin list:

// postcss.config.js
module.exports = {
  plugins: [
    // ...
    require('tailwindcss/nesting'),
    require('tailwindcss'),
    // ...
  ],
}

By default, it uses postcss-nested under the hood (since that's what we use to support nesting in Tailwind plugins), but if you'd like to use postcss-nesting instead, just call our plugin as a function and pass through the postcss-nesting plugin:

// postcss.config.js
module.exports = {
  plugins: [
    // ...
    require('tailwindcss/nesting')(require('postcss-nesting')),
    require('tailwindcss'),
    // ...
  ],
}

Under the hood, this uses a new screen() function we've introduced that you can use to get the expanded media expression from any of your configured breakpoints:

/* Input */
@media screen(sm) {
  /* ... */
}

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

You probably won't need to use this yourself but it could be helpful if you're ever integrating Tailwind with another tool that understands @media but doesn't handle @screen properly.

- @screen sm { /* ... */ }
+ @media screen(sm) { /* ... */ }

Caret color utilities (#4499)

This feature is only available in Just-in-Time mode.

You can now set the color of the cursor in form fields using the new caret-{color} utilities:

<input class="caret-red-500" />

These are customizable using the caretColor key in the theme section of your tailwind.config.js file.

Background origin utilities (#4117)

We've added new utilities for the background-origin property, which let you control where an element's background is positioned relative to the element's border, padding box, or content:

<div class="bg-origin-border p-4 border-4 border-dashed ..." style="background-image: url(...)">
  Background is rendered under the border
</div>

<div class="bg-origin-padding p-4 border-4 border-dashed ..." style="background-image: url(...)">
  Background is rendered within the border but on top of any padding
</div>

<div class="bg-origin-content p-4 border-4 border-dashed ..." style="background-image: url(...)">
  Background is rendered within any padding and under the content
</div>

Learn more in the background origin documentation.

Simplified transform and filter composition (#4604, #4614)

This feature is only available in Just-in-Time mode.

The transform, filter, and backdrop-filter classes are no longer necessary to "enable" their respective set of composable utilities.

- <div class="transform scale-50 filter grayscale backdrop-filter backdrop-blur-sm">
+ <div class="scale-50 grayscale backdrop-blur-sm">

Now those features are automatically enabled any time you use any of the relevant sub-utilities.

It's important to understand though that because these utilities aren't needed anymore, you can no longer expect transforms and filters to be "dormant" by default. If you were relying on conditionally "activating" transforms or filters by toggling these classes, you will want to make sure you are toggling the sub-utilities themselves instead:

- <div class="scale-105 -translate-y-1 hover:transform">
+ <div class="hover:scale-105 hover:-translate-y-1">

I don't expect this will be a real problem for most people, but it's technically a breaking change which is why we've limited this improvment to the JIT engine only.

Per-side border color utilities (#4404)

This feature is only available in Just-in-Time mode.

Requested at least once a month for the last four years, I'm excited to share that we've finally added per-side border color support now that we don't have to sweat the development stylesheet size.

<div class="border-2 border-t-blue-500 border-r-pink-500 border-b-green-500 border-l-yellow-500">
  <!-- ... -->
</div>

Go forth and build ugly websites! (Kidding, kidding, I know they are useful settle the hell down.)

Built-in safelist, transform, and extract support (#4469, #4580)

We've added first-class support for a bunch of important PurgeCSS features and made them work in the JIT engine as well, which doesn't actually even use PurgeCSS.

First is safelist, which is super useful if you need to protect specific classes from being removed from your production CSS, perhaps because they are used in content that comes from a database or similar:

// tailwind.config.js
module.exports = {
  purge: {
    content: ['./src/**/*.html'],
    safelist: [
      'bg-blue-500',
      'text-center',
      'hover:opacity-100',
      // ...
      'lg:text-right',
    ],
  },
  // ...
}

Note that while the classic engine will accept regular expressions here, the JIT engine will not. That's because when we're generating classes on demand, the class doesn't exist until it's used so we have nothing to match the expression against. So if you're using just-in-time mode, make sure you're providing complete class names to get the expected result.

Next is transform, which lets you transform content for different file extensions before scanning it for potential class names:

// tailwind.config.js
let remark = require('remark')

module.exports = {
  purge: {
    content: ['./src/**/*.{html,md}'],
    transform: {
      md: (content) => {
        return remark().process(content)
      },
    },
  },
  // ...
}

This is really useful if you have templates that are written in a language that compiles to HTML, like Markdown.

Finally we have extract, which lets you customize the logic that Tailwind uses to detect class names in specific file types:

// tailwind.config.js
module.exports = {
  purge: {
    content: ['./src/**/*.{html,md}'],
    extract: {
      pug: (content) => {
        return /[^<>"'`\s]*/.match(content)
      },
    },
  },
  // ...
}

This is an advanced feature and most users won’t need it. The default extraction logic in Tailwind works extremely well for almost all projects.

For more information on these features, check out our optimizing for production documentation.

Changes and deprecations

This release introduces a few small changes to the JIT engine that might impact you, and one deprecation:

New dependency tracking system for Just-in-Time mode
Transforms and filters don't need to be "enabled" in Just-in-Time mode
matchUtilities API changes
Deprecate @tailwind screens for @tailwind variants in Just-in-Time mode

It also introduces two minor deprecations for both engines, which are non-breaking for now but will become breaking changes in v3.0 so you are encouraged to account for:

Deprecate lightBlue for sky in the extended color palette
Deprecate blur-0 for blur-none in the default theme

New dependency tracking system for Just-in-Time mode

In Tailwind CSS v2.1, we tracked changes to your template files in just-in-time mode using our own separate watch process because most build tools were missing the APIs we needed to rebuild your CSS when template files changed using the watch system built-in to the build tool.

We've worked hard to make improvements to popular build tools over the past few months and change this, because using our own watch process makes builds prone to race conditions and very hard to debug problems.

So as of Tailwind CSS v2.2, the JIT engine relies on native dependency tracking in build tools by default, with an option to opt-in to the old system if your build tool doesn't support the APIs we need.

If you've followed along closely on GitHub or reported issues with watch mode, you may have seen us suggest using the TAILWIND_DISABLE_TOUCH=true flag — that mode is the default now in v2.2.

This new dependency tracking system is compatible with at least the following tools:

Next.js (>= v10.2.2)
Vite (>= v2.3.8)
webpack 4 (using latest postcss-loader@^4)
webpack 5 (using latest postcss-loader@^5)
Rollup
Snowpack

Tools with known incompatibilities include:

postcss-cli (#383)
Parcel (#6299)

If you discover your build tool isn't yet compatible with the new dependency tracking system, you have two options:

Compile your CSS separately using the new Tailwind CLI. You can use packages like npm-run-all or concurrently to compile your CSS alongside your usual development command by adding some scripts to your project like this:

// package.json
{
  // ...
  "scripts": {
    "dev": "npm-run-all --parallel dev:*",
    "dev:server": "vite",
    "dev:css": "tailwindcss -o src/tailwind.css -w",
    "build": "tailwindcss -o src/tailwind.css && vite build",
    "serve": "vite preview"
  },
}

Set TAILWIND_MODE=watch to opt-in to the old dependency tracking system. If the previous default was working for you, this will let you just keep using that system until the build tool you're using has been updated to support the new system.
```
// package.json
{
  // ...
  scripts: {
    // Set TAILWIND_MODE=watch when starting your dev server
    "dev": "TAILWIND_MODE=watch vite",

    // Do not set TAILWIND_MODE for one-off builds
    "build": "vite build",
    // ...
  },
  // ...
}
```
Note that setting TAILWIND_MODE=watch will start a long-running watch process in the background, so if you set that environment variable when trying to do a one-off build, it will look like the build is hanging. You should only set TAILWIND_MODE=watch when you are actually running a dev server/watch process.

Transforms and filters don't need to be "enabled" in Just-in-Time mode

The transform, filter, and backdrop-filter classes aren't necessary for "enabling" those features when using the JIT engine:

- <div class="transform scale-50 filter grayscale backdrop-filter backdrop-blur-sm">
+ <div class="scale-50 grayscale backdrop-blur-sm">

This means you can no longer expect transforms and filters to be dormant by default, and conditionally activated by adding transform, filter, or backdrop-filter.

Instead, you will want put any variants on the sub-utilities themselves:

- <div class="scale-105 -translate-y-1 hover:transform">
+ <div class="hover:scale-105 hover:-translate-y-1">

`matchUtilities` API changes

The matchUtilities function that is used to register on-demand utilities in the JIT engine has changed significantly.

We consider this private API still which is why we haven't documented it, but I know a few sneaky people out there are playing with it anyways.

To understand how the API works in v2.2, read the pull request that explains the changes.

Deprecate `@tailwind screens` for `@tailwind variants` in Just-in-Time mode

In the classic engine, all utility variants are injected as part of the @tailwind utilities directive.

In the JIT engine, variants like hover and focus are injected in the same place as your responsive variants, which has traditionally been the very end of the stylesheet, or at @tailwind screens if you've included it explicitly.

As of v2.2, the @tailwind screens directive has been renamed to @tailwind variants, since it is now the injection point for all variants, not just responsive variants.

This directive is optional (just like @tailwind screens always has been) and is only useful if you want explicit control over where utility variants are injected. By default, they are always injected at the very end of your stylesheet.

If you were using @tailwind screens before, you should update your code to use @tailwind variants:

  @tailwind base;
  @tailwind components;
  @tailwind utilities;
- @tailwind screens;
+ @tailwind variants;

  /* Some custom CSS... */

The @tailwind variants feature is considered an advanced escape hatch and we recommend omitting it by default. You should only use it if your project won't work properly without it, which is only ever really true if you are introducing Tailwind to a legacy system with a very fragile existing CSS codebase that has styles that absolutely need to be at the very end of the stylesheet for things to work.

Deprecate `lightBlue` for `sky` in the extended color palette

The lightBlue color in the extended color palette has been renamed to sky. It was the only oddball color in the list without a fancy name (like emerald or rose) and we just couldn't stomach it anymore.

Using lightBlue will still work until v3.0, but you'll see a warning in the console suggesting you use the new name.

Note that it's totally okay to start using sky without actually updating your HTML, it's only at the place of import that the name matters:

  // tailwind.config.js
  let colors = require('tailwindcss/colors')

  module.exports = {
    theme: {
      colors: {
        // ...
-       'light-blue': colors.lightBlue,
+       'light-blue': colors.sky,
      }
    }
  }

Deprecate `blur-0` for `blur-none` in the default theme

For some unknown reason when I released Tailwind CSS v2.1 I thought blur-0 was a better name than blur-none, even though every other utility that uses a named size scale (like rounded-md and shadow-lg) use none, not 0.

In v2.2, we've added blur-none and stopped documenting blur-0. It still works, but it'll be removed from the default theme configuration in v3.0.

- <div class="blur-0">
+ <div class="blur-none">

Fixes and improvements

Alongside the new features this release introduces, we've also fixed a bunch of little things that might have been bugging you.

Here's a list of the fixes and improvements we've made since the last release, with links to the relevant pull requests to learn more:

JIT: Support applying important utility variants (#4260)
JIT: Improve support for Svelte class bindings (#4187)
JIT: Improve support for calc and var in arbitrary values (#4147)
Convert hsl colors to hsla when transforming for opacity support instead of rgba (#3850)
Fix backdropBlur variants not being generated (#4188)
Improve animation value parsing (#4250)
Ignore unknown object types when hashing config (82f4eaa)
Ensure variants are grouped properly for plugins with order-dependent utilities (#4273)
Resolve purge paths relative to tailwind.config.js instead of the current working directory (#4214)
JIT: Fix temp file storage when node temp directories are kept on a different drive than the project itself (#4044)
Support border-opacity utilities alongside default border utility (#4277)
JIT: Fix source maps for expanded @tailwind directives (2f15411)
JIT: Ignore whitespace when collapsing adjacent rules (15642fb)
JIT: Generate group parent classes correctly when using custom separator (#4508)
JIT: Fix incorrect stacking of multiple group variants (#4551)
JIT: Fix memory leak due to holding on to unused contexts (#4571)

If you read this whole thing well damn, well done. Thanks as always for being part of the community and I hope you have fun with the new goodies!

tailwindcss 2.2.0 on Node.js NPM

Tailwind CSS v2.2.0

New features

All-new improved Tailwind CLI (#4526, #4558)

Before and after pseudo-element variants (#4461)

First-letter/line variants (#4482)

Selected text variants (#4482)

List marker variants (#4482)

Sibling selector variants (#4556)

Exhaustive pseudo-class support (#4482)

Shorthand color opacity syntax (#4348)

Extended arbitrary value support (#4263)

Improved nesting support (#4318)

Caret color utilities (#4499)

Background origin utilities (#4117)

Simplified transform and filter composition (#4604, #4614)

Per-side border color utilities (#4404)

Built-in safelist, transform, and extract support (#4469, #4580)

Changes and deprecations

New dependency tracking system for Just-in-Time mode

Transforms and filters don't need to be "enabled" in Just-in-Time mode

matchUtilities API changes

Deprecate @tailwind screens for @tailwind variants in Just-in-Time mode

Deprecate lightBlue for sky in the extended color palette

Deprecate blur-0 for blur-none in the default theme

Fixes and improvements

tailwindcss 2.2.0
on Node.js NPM

`matchUtilities` API changes

Deprecate `@tailwind screens` for `@tailwind variants` in Just-in-Time mode

Deprecate `lightBlue` for `sky` in the extended color palette

Deprecate `blur-0` for `blur-none` in the default theme