Upcoming Changes

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...
    ],
  },
  // ...
}

Default line heights for font size utilities

In Tailwind v2.0, all font-size utilities like text-sm and text-lg will also include their own default line-height value specific to that font size.

Here's a list of the included font-size utilities with their corresponding default line-heights:

// Default config for 2.0

module.exports = {
  // ...
  theme: {
    fontSize: {
      xs: ['0.75rem', { lineHeight: '1rem' }],
      sm: ['0.875rem', { lineHeight: '1.25rem' }],
      base: ['1rem', { lineHeight: '1.5rem' }],
      lg: ['1.125rem', { lineHeight: '1.75rem' }],
      xl: ['1.25rem', { lineHeight: '1.75rem' }],
      '2xl': ['1.5rem', { lineHeight: '2rem' }],
      '3xl': ['1.875rem', { lineHeight: '2.25rem' }],
      '4xl': ['2.25rem', { lineHeight: '2.5rem' }],
      '5xl': ['3rem', { lineHeight: '1' }],
      '6xl': ['4rem', { lineHeight: '1' }],
    },
  },
}

This is a breaking change because you might be using a utility like text-2xl in your project right now without adding an explicit line-height like leading-8, which means you are implicitly relying on the current default of 1.5 and the new defaults will change how your project looks.

The easiest way to update your project for 2.0 is to look through your project for any places where you are using a font-size utility without adding a line-height utility and explicitly add leading-normal, so that when you upgrade to 2.0 the new line-height defaults won't impact your design.

To opt-in to this change now and ease the transition to 2.0, use the defaultLineHeights flag:

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

Rename font-thin and font-hairline

In Tailwind 2.0, the font-thin utility will be renamed to font-extralight and font-hairline will be renamed to font-thin to better match the naming in the OpenType specification.

To opt-in to this change now and ease the transition to 2.0, use the standardFontWeights flag:

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