Tailwind UI for Tailwind CSS v2.0

We recently released Tailwind CSS v2.0, the first major update to Tailwind CSS ever. For more information about what's new, read the announcement post.

Tailwind CSS v2.0 is our attempt to take everything we've learned building Tailwind UI and make sure that everything you need to build great user interfaces is included in the box — not hiding away in the @tailwindcss/ui plugin.

This article covers everything you need to know about continuing to work with Tailwind UI on Tailwind CSS v1.0 projects, what updates we've made in Tailwind UI, and how to update your Tailwind UI projects for Tailwind CSS v2.0.

Accessing Tailwind UI for Tailwind CSS v1.0

First and foremost, we understand that not everyone is in a position to drop what they are working on and upgrade to Tailwind CSS v2.0 right away.

If you purchased a Tailwind UI license before Tailwind CSS v2.0 was released, you will always be able to access the previous version here:

Browse Tailwind UI for Tailwind CSS v1.0

You can access this link at any time from the account dropdown in the top right corner of your screen.

What's changed in Tailwind UI

We've updated all of the Tailwind UI examples to account for the small breaking changes in Tailwind CSS v2.0, and made some small visual improvements where we were able to take advantage of some of the cool new features.

@tailwindcss/ui is no longer needed

When we started working on Tailwind UI, we kept finding ourselves needing things that weren't included in Tailwind CSS by default, like enabling extra variants, adding values to the spacing scale, improving the color palette, etc.

To deal with this, we created the @tailwindcss/ui plugin to serve as our set of extensions that we used to build the examples in Tailwind UI, with the goal to eventually make it unnecessary by upstreaming our improvements into Tailwind CSS itself.

Tailwind CSS v2.0 includes an all-new color palette, extended spacing and typography scales, new focus ring utilities, and way more default variants, all inspired by what we learned dog-fooding the framework for Tailwind UI.

Tailwind UI for Tailwind CSS v2.0 relies solely on the default Tailwind configuration, with certain examples also requiring first-party plugins like @tailwindcss/typography, @tailwindcss/aspect-ratio, or the new @tailwindcss/forms plugin.

When needed, these are documented right at the top of the code snippet, so you know what you need to do without reading Tailwind UI-specific any setup documentation at all.

*-max-content and *-min-content changed to *-max and *-min

In addition to the couple of class name changes in the Tailwind CSS v2.0 upgrade guide, the max-content and min-content width/max-width/min-width utilites have been renamed to just *-max and *-min.

Old New
max-w-max-content max-w-max
max-w-min-content max-w-min
min-w-max-content min-w-max
min-w-min-content min-w-min
w-max-content w-max
w-min-content w-min

Colors have been updated

Tailwind CSS v2.0 includes a new color palette, which is heavily based on what we learned building and using the color palette we designed for Tailwind UI.

For the most part the colors are just minor improvements to what was included in @tailwindcss/ui, especially for gray and indigo which are by far the most commonly used colors throughout Tailwind UI.

Some colors like yellow are have changed significantly because we've decided to stop chasing the idea of a perceptually uniform color palette. After years of experimentation, it's become clear that trying to make yellow-500 the same perceived brightness as indigo-500 isn't productive — part of what makes yellow yellow is that it looks lighter than colors like blue. Trying to change that is just going to war with nature.

For the most part, you probably won't be able to tell the difference between the colors when comparing the original examples to the updated ones.

Forms rely on the new @tailwindcss/forms plugin

Previously we bundled a bunch of opinionated form classes like form-input and form-checkbox with the @tailwindcss/ui plugin and used those through the Tailwind UI examples.

Alongside Tailwind CSS v2.0, we've released a new @tailwindcss/forms plugin that aims to drastically simplify how you customize form elements with Tailwind.

As part of updating Tailwind UI for Tailwind CSS v2.0, we've removed the use of all the special form-* classes and moved to the new @tailwindcss/forms plugin instead, with any style customizations added directly to the templates with utility classes.

Check out this form layout example to see the code looks now.

Aspect-ratios are now handled with the @tailwindcss/aspect-ratio plugin

Some examples in Tailwind UI were using classes like pb-3/5 along with some positioning tricks to give elements a specific aspect ratio.

As part of this update, we've replaced those tricks with the @tailwindcss/aspect ratio class, which removes the need to add all of those fractional values to the padding scale.

Focus styles have been revamped

One of the things we were never totally happy with in Tailwind UI were the custom focus styles. It felt like we were always reinventing a new style on an element-by-element basis, and while those styles looked nice in isolation, when you started trying to navigate an entire page with the keyboard, the difference in the focus styles from element-to-element actually made it a little hard to follow what you were focused on. Many of the focus styles were also a bit too subtle, which isn't great for accessibility.

We spent a few weeks trying to solve this problem and came up with the new ring utilities, included in Tailwind CSS v2.0.

We've updated the focus styles across the board to be much more consistent, and I think the user experience on our full page examples is much better now.

Check out this form layout example for an idea of what the focus style we're using by default looks like now.

Fewer transitions

We've reduced the number of transitions used in the examples which makes everything feel a lot snappier. Instead of almost every interactive element having transition ease-in-out duration-150 tacked on to the end, most of those transitions are now instant.

If you preferred that look, Tailwind CSS v2.0 actually lets you bring it back with just transition now, as ease-in-out and duration-150 are the new defaults when a transition is added.

Updating for Tailwind UI users

First things first, you don't have to upgrade your project to Tailwind CSS v2.0 if you can't justify it or don't want to. You will always have access to Tailwind UI for Tailwind CSS v1.0 and the @tailwindcss/ui plugin will continue to work.

That said, the biggest motivation for releasing Tailwind CSS v2.0 was to improve the Tailwind UI experience, so I'd recommend upgrading if you can squeeze it in.

Remove @tailwindcss/ui, then update tailwindcss

Start by removing @tailwindcss/ui from your tailwind.config.js file:

  // tailwind.config.js
  module.exports = {
    plugins: [
-     require('@tailwindcss/ui')
    ]
  }

After that, follow the Tailwind CSS v2.0 upgrade guide, then come back here for some Tailwind UI-specific advice.

Add first-party plugins

Coming from @tailwindcss/ui, you'll want to install our three first-party plugins instead:

npm install @tailwindcss/forms @tailwindcss/typography @tailwindcss/aspect-ratio

Then add them to your tailwind.config.js file:

// tailwind.config.js
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    require('@tailwindcss/aspect-ratio'),
  ]
}

We'll discuss each of these plugins in detail further below.

Color palette changes

Tailwind CSS v2.0 includes a new color palette which is heavily inspired by but a bit different than the color palette included in @tailwindcss/ui.

Many of you are probably already using a custom color palette that matches the branding of whatever you're building, so for you this won't matter. Keep using your custom colors, and whenever you pull in an example from Tailwind UI just adjust the markup to use your custom colors as needed.

If you're relying directly on the color palette included with @tailwindcss/ui, you have two options:

1. Carry the original colors forward

If you are using the default colors from @tailwindcss/ui and are totally happy with how your site looks, there's no reason to not just keep using those colors.

Tailwind UI has always been designed for a "copy it, adjust it, own it" workflow. The idea from day one was that you'd pick one of our examples as a starting point, pull it into your project, and customize it to fit your needs.

See this example configuration that includes all of the @tailwindcss/ui colors if you'd like to keep using them.

2. Use the new color palette

If you are using the default colors from @tailwindcss/ui and want to migrate to the new Tailwind CSS v2.0 color palette, you don't need to make any changes to your config file.

Instead, you will want to click around your site with the new color palette enabled and see if anything looks off to you, and make the necessary adjustments in your HTML to switch to a different shade of whatever color looked drastically different than before.

If you are mostly using gray and indigo, it's unlikely you'll need to change anything.

You can always reference any of the components you copied from Tailwind UI to see what colors we are using now as well.

Form styles

Once you've installed the new @tailwindcss/forms plugin, you'll notice your forms look quite a bit different than they did previously (assuming you hadn't done any other customizations).

The first thing you need to do is make sure you add type="text" to any <input> elements that are missing a type. If you skip this step, the forms plugin won't reset the styles for those elements.

- <input ...>
+ <input type="text" ...>

After this, as with colors you have two choices:

1. Recreate your existing form styles

To get a regular <input> element looking exactly the way it did before, you'll want to give them your desired border radius and border color, then use the new ring utilities to recreate the previous focus.

Here's an example:

- <input type="text" class="form-input block w-full sm:text-sm sm:leading-5">
+ <input type="text" class="block w-full border-gray-300 rounded-md focus:border-blue-300 focus:ring focus:ring-blue-200 focus:ring-opacity-50 sm:text-sm sm:leading-5">

It's a few more classes, but this is because the new @tailwindcss/forms plugin is much less opinionated and designed to support many more use cases. You can extract these away into your own form-input class if you like, or into a JS component if you're using a framework like React or Vue.

2. Use the new form styles

If you really just want to stick to Tailwind UI exactly as it comes out of the box, reference the updated form examples in Tailwind UI itself to see how things are styled and update your markup to match.

Here's an example of what the code for a basic input looks like after this update:

<input type="text" class="border-gray-300 rounded-md focus:ring-indigo-500 focus:border-indigo-500 sm:max-w-xs sm:text-sm">

Focus styles

We've updated focus styles across the board to be more visually consistent and more accessible.

It's hard to give guidance on exactly what to change here because previously so many focus styles were very custom per-element, but generally we are just using a 2px ring for custom focus styles now, using the new ring utilities.

We've also removed custom focus styles for anything that doesn't receive focus when interacting with it with the mouse, so for example all <a> tags now just rely on the default browser focus style, as you only see it when navigating with the keyboard and using a familiar focus indicator where possible is much better for usability than using something custom.

Enable any necessary variants

We've removed the need for group-focus and active entirely in the updated Tailwind UI examples, but if you're using them in your own code, you'll want to enable them wherever you need it.

Here is an example of how you can re-enable all of the variants that were being previously enabled in @tailwindcss/ui that are not enabled by default in Tailwind CSS v2.0:

// tailwind.config.js
module.exports = {
  // ...
  variants: {
    extend: {
      backgroundColor: ['group-focus', 'active'],
      borderColor: ['group-focus'],
      boxShadow: ['group-focus'],
      opacity: ['group-focus'],
      textColor: ['group-focus', 'active'],
      textDecoration: ['group-focus'],
    }
  }
}

Removed shadow utilities

The @tailwindcss/ui plugin included shadow-outline-{color} utilities and a shadow-solid utility that are not included in Tailwind CSS v2.0.

Both of these can be replaced with the new ring utilities which are a much better general purpose solution to this problem.

If you want to keep the old utilities around, you can add them to your config file:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      boxShadow: {
          solid: '0 0 0 2px currentColor',
          outline: `0 0 0 3px rgba(156, 163, 175, .5)`,
          'outline-gray': `0 0 0 3px rgba(254, 202, 202, .5)`,
          'outline-blue': `0 0 0 3px rgba(191, 219, 254, .5)`,
          'outline-green': `0 0 0 3px rgba(167, 243, 208, .5)`,
          'outline-yellow': `0 0 0 3px rgba(253, 230, 138, .5)`,
          'outline-red': `0 0 0 3px rgba(254, 202, 202, .5)`,
          'outline-pink': `0 0 0 3px rgba(251, 207, 232, .5)`,
          'outline-purple': `0 0 0 3px rgba(221, 214, 254,, .5)`,
          'outline-indigo': `0 0 0 3px rgba(199, 210, 254, .5)`,
      }
    }
  }
}

Here we've used colors based on the new Tailwind CSS v2.0 color palette, but you can use the same general approach for any color. We've used 300 for gray and 200 for the rest of the colors at 50% opacity here.

Aspect-ratios

There are a couple of examples in Tailwind UI for Tailwind CSS v1.0 that use utilities like pb-3/5 with some positioning trickery to simulate aspect ratios.

To update these for Tailwind CSS v2.0 you have two options:

1. Use the new aspect-ratio plugin

The best solution in our opinion is to use the new @tailwindcss/aspect-ratio plugin. Look for situations where you used percentage padding utilites like pb-9/16 and replace them with aspect-* utilites like this:

- <div class="relative pb-9/16">
-   <div class="absolute inset-0 h-full w-full ...">
+ <div class="aspect-h-9 aspect-w-16">
+   <div class="...">

2. Add fractional values to your padding scale

If you don't want to update your HTML, you can extend your padding scale to include all of the fractional values previously added by @tailwindcss/ui and things will just work:

// tailwind.config.js
module.exports = {
  // ...
  theme: {
    extend: {
      padding: {
        '1/2': '50%',
        '1/3': '33.333333%',
        '2/3': '66.666667%',
        '1/4': '25%',
        '2/4': '50%',
        '3/4': '75%',
        '1/5': '20%',
        '2/5': '40%',
        '3/5': '60%',
        '4/5': '80%',
        '1/6': '16.666667%',
        '2/6': '33.333333%',
        '3/6': '50%',
        '4/6': '66.666667%',
        '5/6': '83.333333%',
        '1/12': '8.333333%',
        '2/12': '16.666667%',
        '3/12': '25%',
        '4/12': '33.333333%',
        '5/12': '41.666667%',
        '6/12': '50%',
        '7/12': '58.333333%',
        '8/12': '66.666667%',
        '9/12': '75%',
        '10/12': '83.333333%',
        '11/12': '91.666667%',
        full: '100%',
      }
    }
  }
}

Typography/content blocks

The @tailwindcss/typography plugin has been updated for Tailwind CSS v2.0, so once you install it you should be more or less good to go.

The only difference is that now instead of customizing link colors in your config file, you can use classes like prose-indigo to add the color directly in your HTML:

- <div class="prose">
+ <div class="prose prose-indigo">

You won't need any typography related stuff in your tailwind.config.js file unless you have customizations you'd like to apply yourself. No customizations are needed for Tailwind UI for Tailwind CSS v2.0.