Upcoming Changes

Updates and deprecations coming in the future and how to prepare for them.


Tailwind follows semantic versioning, so we never introduce breaking changes until a new major release (v2.0 is the next one).

Rather than drop a bunch of breaking changes on you at once though, we use feature flags as an incremental adoption strategy so you can opt-in to breaking changes early, and save the upgrade hassle down the road.

The following breaking changes are currently available in Tailwind behind flags.

Remove deprecated gap utilities

Tailwind v1.7.0 introduced new gap-x-{n} and gap-y-{n} utilities to replace the existing col-gap-{n} and row-gap-{n} utilities. We currently include both by default, but the old utilities will be removed in v2.0.

To opt-in to removing them now, use the removeDeprecatedGapUtilities flag:

// tailwind.config.js
module.exports = {
  future: {
    removeDeprecatedGapUtilities: true,
  },
  // ...
}

Purge layers by default

Tailwind v1.8.0 introduced new layers purge mode which will be the default in v2.0. It purges all layers (base, components, and utilities) by default, whereas the previous default mode (conservative, now deprecated) only purged the utilities layer.

With the introduction of the new preserveHtmlElements purge option (which is true by default), we consider this more aggressive purging mode very safe, and it is unlikely to actually be a breaking change in your application.

You should see an even smaller CSS file by default with the new layers mode enabled, and shouldn't see any negative consequences unless you were deliberately relying on the fact that Tailwind was previously not purging the base or components layers by default.

To opt-in to using the new layers mode by default, use the purgeLayersByDefault flag:

// tailwind.config.js
module.exports = {
  future: {
    purgeLayersByDefault: true,
  },
  // ...
}

If you'd like to only purge the utilities layer (like the conservative mode did), you can still opt-in with this flag, but then explicitly specify that you'd only like to purge the utilities layer:

// tailwind.config.js
module.exports = {
  future: {
    purgeLayersByDefault: true,
  },
  purge: {
    layers: ['utilities'],
    content: [
      // Paths to your templates...
    ],
  },
  // ...
}

Tailwind UI is now in early access!