Tailwind CSS v3.0.0-alpha.1

[adamwathan]

Tailwind CSS v3.0.0-alpha.1

The first alpha release of Tailwind CSS v3.0 is here! If you don't even care what's changed and just want to start using it right now, install it via npm:

npm install -D tailwindcss@next

If you're using @tailwindcss/typography or @tailwindcss/forms, you'll want to update those packages as well:

npm install -D @tailwindcss/typography@next
npm install -D @tailwindcss/forms@next

We've also got a brand new CDN build you can play with if you want, too.

Remember this is an alpha release, so some things might be broken. I don't know about them otherwise I would have fixed them, but you are gonna find them! So try it, break it, and tell me about it when you do so we can get this thing really battle-tested for a proper v3.0 release later this year.

What's new

• Just-in-Time, all the time — the new Just-in-Time engine has replaced the classic engine, offering big performance benefits and all-new features like stackable variants, arbitrary value support, and more (#5340)
• Just-in-Time CDN build, for prototyping with the full power of Tailwind CSS without a build step
• Every color by default, including all of the extended palette colors like cyan, rose, fuchsia, and lime, and fifty shades of grey gray (#5384)
• New aspect-ratio utilities, using the new native aspect-ratio property (#5359)
• New accent-color utilities, for setting the color of a form input's accent (#5387)
• New scroll-snap utilities, for CSS-only scroll snapping (#5637)
• New scroll-behavior utilities, for browser-native smooth scrolling (#5388)
• New text-indent utilities, for indenting the first line in a paragraph (#5449)
• New column and break-before/inside/after utilities, for wrapping multi-column content (#5457, #5530)
• New touch-action utilities, for controlling touchscreen interactions (#5603)
• New will-change utilities, for optimizing transition performance (#5448)
• New border-x and border-y utilities, for styling left/right and top/bottom borders a the same time (#5639)
• New file: variant, for styling the native file upload button (#4936)
• New open: variant, for styling open <details> and <dialog> elements (#5627)

What's changed

We've tried really hard to keep the breaking changes to a minimum, and this should be a really smooth upgrade — especially if you were already using the JIT engine.

Start by reading the Just-in-Time mode changes in the documentation, and then come back here for a couple more steps.

purge has changed to content

The JIT engine doesn't actually use PurgeCSS under-the-hood, so purge doesn't feel like the right name for these configuration options anymore.

Now this configuration should look like this:

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.html' /* ... */],
}

For more complex configurations, it should look something like this:

// tailwind.config.js
module.exports = {
  content: {
    files: ['./src/**/*.html' /* ... */],
    transform: {
      md: (content) => {
        return remark().process(content)
      },
    },
    extract: {
      md: (content) => {
        return content.match(/[^<>"'`\s]*/)
      },
    },
  },
  safelist: [
    'font-bold',
    'text-center',
    { pattern: /bg-(red|blue|green)/, variants: ['hover', 'focus'] },
  ],
  // ...
}

We've tried really hard to make Tailwind smart enough to understand the old configuration as well, so with any luck your existing configuration should still work, but you'll want to update to the new format to silence the annoying console warnings we blast you with.

Color name changes

As part of enabling the extended color palette by default, a few color names needed to change due to collisions.

See the pull request for all of the details you need to upgrade. It should only be a couple of lines of code in your tailwind.config.js file.

overflow-clip has changed to text-clip

Those damn browser developers added a real overflow: clip property, so using overflow-clip for text-overflow: clip is a really bad idea now.

We've renamed it to text-clip, and now overflow-clip adds overflow: clip like you'd expect. We've also renamed overflow-ellipsis to text-ellipsis, but overflow-ellipsis still secretly works.

- <div class="overflow-clip">
+ <div class="text-clip">

PostCSS 7 is no longer supported

If you were using the @tailwindcss/postcss7-compat package because you are stuck on PostCSS 7, you'll need to upgrade to PostCSS 8 before you can upgrade to Tailwind CSS v3.0.0-alpha.1.

I think this is mostly create-react-app users, and thankfully they are close to releasing a new version that uses webpack 5 and supports PostCSS 8 by default.

Just-in-Time CDN

Something that has always sucked about our CDN builds is that we always had to disable tons of awesome features to keep the file size down to something the browser was willing to parse.

For Tailwind CSS v3.0, we're doing it differently. Inspired by some awesome work Marcel Pociot did on tailwindcss-jit-cdn, we've built a JS library that compiles Tailwind in the browser, and uses MutationObserver to keep track of all of the classes you're using.

It lets you use every feature Tailwind CSS has to offer, and does it in 93kB — which ain't bad for something originally designed to run in node with no file size considerations at all.

The Just-in-Time CDN is intended for development purposes only, and should not be used in production.

Why shouldn't it be used in production?

The biggest reason is because it uses MutationObserver to add the styles, it can't detect styles for dynamically created elements fast enough to avoid a flash of unstyled content (FOUC).

For example, say you have some JavaScript that opens a modal, and the modal is supposed to transition in when it opens. When the modal opens, the HTML for it is inserted into the DOM right away, but the styles might not exist for it yet because you haven't used those same classes elsewhere in the file. The observer will fire, and Tailwind will generate the styles, but the modal is already open, so you're going to see an unstyled flash the first time it opens.

We recommend pulling in the JIT CDN as a blocking (so not deferred) script to avoid the FOUC for the very initial render, but that of course means it adds 100ms (or whatever) before the page is even rendered. Not a big deal really but using a static CSS file is way faster.

It's also quite large (almost 100kB compressed) whereas compiling your CSS ahead of time usually leads to something closer to 10kb compressed, and with no run time overhead.

TLDR; It's probably fine for simple static pages but it's really much better to build the static CSS file.

To try it out, throw this <script> tag in your <head>:

  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Example</title>
+     <script src="https://cdn-tailwindcss.vercel.app/"></script>
    </head>
    <body>
      <!-- -->
    </body>
  </html>

We'll give it a more permanent URL in the future but this is good enough for the alpha.

Using first-party plugins

First-party plugins can be automatically loaded using the plugins query parameter:

<script src="https://cdn-tailwindcss.vercel.app/?plugins=forms,typography,aspect-ratio,line-clamp"></script>

The plugins parameter accepts a comma-separated list of plugins, and you can optionally specifiy a version number or range for each plugin, for example ?plugins=forms@0.3.4,typography@^0.5

Customizing your config

To customize your Tailwind CSS configuration, override tailwind.config:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example</title>
    <script src="https://cdn-tailwindcss.vercel.app/"></script>
    <script>
      tailwind.config = {
        theme: {
          extend: {
            colors: {
              tomato: 'tomato',
            },
          },
        },
      }
    </script>
  </head>
  <body>
    <!-- -->
  </body>
</html>

Adding custom CSS

Use <style type="text/tailwindcss"> elements to add any custom CSS that that you'd like to process with Tailwind:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example</title>
    <script src="https://cdn-tailwindcss.vercel.app/"></script>
    <style type="text/tailwindcss">
      body {
        @apply bg-pink-500;
      }
    </style>
  </head>
  <body>
    <!-- -->
  </body>
</html>

---

So there you have it! Again, this is an alpha release so there are probably going to be some issues, but play with it and report any problems you find so we can get it all cleaned up for a proper release in a month or two.

Thanks to community members @bytedance, @htunnicliff, @DoctorDerek, @lukewarlow, @codytooker, @nifte, @ericbf, @kwaa, @MatteoGauthier, @geshii, @sachinraja, @TCatinaud, @iksaku, @seanpdoyle, @95jonpet, @innocenzi, @DavydeVries, and @hardfist for your contributions to this release — lots of good ideas and improvements made it in thanks to you ❤️

---

This discussion was created from the release v3.0.0-alpha.1.

[vlados]

Why major release? I am not seeing so many changes from the latest release, so why this is not 2.3?

[chasegiunta]

There are breaking changes.

[hudadamar21]

maybe jit mode as default engine and purge to content is a major update

[reinink]

The primary reason the JIT engine is considered a breaking change from the previous AOT mode is because Tailwind now requires that you provide a list of all your template files. This is necessary as the JIT mode generates your CSS on-demand by scanning these files for Tailwind classes, and only generates the CSS needed for them.

In many ways this is similar to how things worked in Tailwind 2.x with the purge option enabled. However, enabling PurgeCSS was an optional step in 2.x — whereas in 3.0 providing a list of template files via the content option is required. Failing to do so will result in no CSS being generated for the Tailwind utility classes.

But yeah, beyond that, there really aren't any major breaking changes. Just little things like overflow-clip being renamed to text-clip, PostCSS 7 support being dropped, and some color name changes.

[jenstornell]

To keep minor releases to new features and bug fixes and major releases for the same + breaking changes is a great idea. So don't change the workflow, it's perfect.

[jshimkoski]

I'm pretty sure the Tailwind CSS guys use Semantic Versioning.

In short, that means MAJOR.MINOR.PATCH:

MAJOR = Breaking change
MINOR = Backward compatible new features
PATCH = Backward compatible bug fixes

This is the recommended versioning technique for npm.

[joshmanders]

YAYYYYY!!! Congrats on this alpha release, @adamwathan and team!

[VicGUTT]

JIT by default & first party JIT/Tailwind in the browser support ! ❤️

This isn't mentioned in the release note but is it safe to assume third party/custom plugins would also work ?
If yes, pretty much the same approche as what the BeyondCode folks had (scroll down to Custom plugins) ? :

<!-- Include CDN JavaScript -->
<script src="https://unpkg.com/tailwindcss-jit-cdn"></script>

<!-- Specify a custom TailwindCSS configuration -->
<script type="module" >
import tailwindcssTypography from 'https://cdn.skypack.dev/@tailwindcss/typography';

window.tailwindConfig = {
	plugins: [
		tailwindcssTypography,
	]
};

window.tailwindCSS.refresh();
</script>
<script type="tailwind-config">
window.tailwindConfig
</script>

[VicGUTT]

Realized, after posting my comment, that I could simply test it for myself, silly me ! ^^

Aaaaannnd... I'm happy to report that it... DOES ! So great !
Here's a quick example:

<script src="https://cdn-tailwindcss.vercel.app/"></script>

<script type="module">
    import tailwindcssTypography from 'https://cdn.skypack.dev/@tailwindcss/typography';

    tailwind.config = {
        plugins: [
            tailwindcssTypography,
        ]
    };
</script>

Thanks to both BeyondCode & TailwindLabs teams ✌🏾

[adamwathan]

Yep it works! 🙌

[VicGUTT]

Exciting times 👌

[okikio]

Looks awesome, but I'd highly suggest setting up versioning for the CDN build.

[adamwathan]

Yep already works! Just stick it as the first route param:

https://cdn-tailwindcss.vercel.app/3.0.0-alpha.1

You'll see you are automatically redirected to a static version URL if you visit https://cdn-tailwindcss.vercel.app in the browser.

[okikio]

Awesome

[dcastil]

Will there be any additional features in the final v3.0.0 release? Just want to know whether I should update my downstream library or wait some more time. 😊

[adamwathan]

Probably a few more things yeah 👍🏻 I have a PR open for flex-basis utilities for example and I’m sure we’ll have a couple more ideas before the release in ~November.

[sinyayadynya]

Now my custom theme can't find node_modules/tailwindcss/dist/base.min.css, which don't exist anymore, any idea what can be wrong?

[VicGUTT]

I guess this is to be expected since there is no more a dist folder and AOT mode is gone; so there is nothing to compile and distribute as CSS files.

You can see the dist folder being gone if you take a look at the v2.2.16 tag and v3.0.0-alpha.1 tag.

[sinyayadynya]

Thanks! I made one step ahead, but still missing base.css. Have opened another discussion here: #5678

[ghost]

What about compatibility with the current Tailwind/Headless UI?

[adamwathan]

All fine 👍🏻

[pheuter]

The Just-in-Time CDN is intended for development purposes only, and should not be used in production.

Why shouldn't it be used in production?

[emptynick]

My guess is that it will take a lot of time parsing your html compared to a compiled/bundled css file

[adamwathan]

The biggest reason is that because it uses MutationObserver to add the styles, it can't detect styles for dynamically created elements fast enough to avoid FOUC.

For example, say you have some JavaScript that opens a modal, and the modal is supposed to transition in when it opens. When the modal opens, the HTML for it is inserted into the DOM right away, but the styles might not exist for it yet because you haven't used those same classes elsewhere in the file. The observer will fire and Tailwind will generate the styles, but the modal is already open, so you're going to see an unstyled flash the first time it opens.

We recommend pulling in the JIT CDN as a blocking (so not deferred) script yo avoid the FOUC for the very initial render, but that of course means it adds 100ms or whatever before the page is even rendered. Not a big deal really but using a static CSS file is way faster.

It's also quite large (almost 100kB compressed) whereas compiling your CSS ahead of time usually leads to something closer to 10kb compressed, and with no run time overhead.

It's probably fine for simple static pages but it's really much better to build the static CSS file.

[pheuter]

Appreciate the thoughtful response, makes sense 👌 Congrats on the release!

[dammy001]

Congratulations on this alpha release, @adamwathan, and the team. I'd check this out while awaiting the stable release

[robertdrakedennis]

Just a quick reply, I think it would be worth pinning this discussion as it kinda gets lost when viewing "all" discussions, congrats on the first v3 release, really looking forward to the new website :)

[ghost]

It's the only one in the announcements¹ category

Footnotes

1. https://github.com/tailwindlabs/tailwindcss/discussions/categories/announcements ↩

[m1keyboy]

Congratulations on the release - looks great.

With JIT now the default, do you have any plans to revisit the way you've implemented theming? (i.e. so it's possible to support more than just default and 'dark')

[fahmiidris]

Will it be difficult to upgrade from version 2.x because of this engine default change?

[reinink]

Nope, it's a pretty easy upgrade, especially if you're already using PurgeCSS in your 2.x project. If you were not previously purging, you'll need to set the content option in your tailwind.config.js file to tell Tailwind CSS where your template files are, since JIT mode generates your CSS on-demand by scanning these files for Tailwind classes. You can read more about that here.

Just be aware that the purge option from v2.2 has been renamed to content in v3.0 — although even this isn't a breaking change, you'll just get a console warning if you use the old property name.

[venkat-gvk]

Finally JIT by default. So excited. Waiting for create-react-app to use postcss8 by default.

[joshmedeski]

This is great news guys, congrats! Can't wait to see people like CodePen use the new JIT CDN feature for quick pins ;)

[ghost]

Starter Template Vue 3 + Tailwind 3 on CodePen

[henribru]

Mentioned this on the Discord but reposting it here in case it went unnoticed:

PostCSS 7 is no longer supported

If you were using the @tailwindcss/postcss7-compat package because you are stuck on PostCSS 7, you'll need to upgrade to PostCSS 8 before you can upgrade to Tailwind CSS v3.0.0-alpha.1.

I think this is mostly create-react-app users, and thankfully they are close to releasing a new version that uses webpack 5 and supports PostCSS 8 by default.

This also affects Vue CLI users, which might be worth mentioning in the release notes. Actually Vue CLI is also close (there's a beta) to releasing a new version that uses webpack 5 and supports PostCSS 8 by default, so really just changing it to say "create-react-app/vue-cli" would be accurate.

[jenstornell]

I was just wondering about that. I use Vue3 with Vue CLI. I had to install it with PostCSS7 with the instructions from the Tailwind docs. The thing is not that Tailwind now require PostCSS8, but that Vue CLI still doesn't. Should be in the docs anyway to save everyone from unneeded support questions.

[Anay-v2]

The @apply with CDN blows my mind. Like how did you do that???

[jenstornell]

@adamwathan is a true wizard. However, I will probably never use the CDN version. Be careful because of the cons mentioned in the post.

[v-erse]

We'll give it a more permanent URL in the future but this is good enough for the alpha.

How long until you change the URL? And will https://cdn-tailwindcss.vercel.app/ still work after you do that? I'm assuming it will but asking just in case.

[reinink]

The URL will most likely change when we officially launch Tailwind CSS v3.0 in a month or two. And yes, I suspect that https://cdn-tailwindcss.vercel.app/ will continue working after that.

[sebastiaanluca]

Great job! 🔥

I've followed the guide and upgraded, but getting this error with Vite (only when running vite without parameters, so dev server). vite build builds the production files just fine.

[vite] Internal server error: contentMatchCache is not defined
  Plugin: vite:css
  File: project/resources/css/global.css
      at project/node_modules/tailwindcss/lib/lib/expandTailwindAtRules.js:233:50
      at project/node_modules/tailwindcss/lib/processTailwindFeatures.js:40:53
      at plugins (project/node_modules/tailwindcss/lib/index.js:22:68)
      at LazyResult.runOnRoot (project/node_modules/vite/node_modules/postcss/lib/lazy-result.js:339:16)
      at LazyResult.runAsync (project/node_modules/vite/node_modules/postcss/lib/lazy-result.js:391:26)
      at async compileCSS (project/node_modules/vite/dist/node/chunks/dep-24231913.js:34041:27)
      at async TransformContext.transform (project/node_modules/vite/dist/node/chunks/dep-24231913.js:33628:50)
      at async Object.transform (project/node_modules/vite/dist/node/chunks/dep-24231913.js:50590:30)
      at async doTransform (project/node_modules/vite/dist/node/chunks/dep-24231913.js:64911:29)

global.css:

@import 'tailwindcss/base';
@import './partials/typography.css';
@import 'tailwindcss/components';
@import './partials/layout.css';

Same with:

@tailwind base;
@tailwind components;
@tailwind utilities;

tailwind.config.js:

module.exports = {
    content: [
        './resources/views/**/*.blade.php',
        './resources/scripts/**/*.{vue,js,ts,jsx,tsx}',
    ],
}

Any thoughts on how to debug this?

---

It tries to run:

console.log('Potential classes: ', candidates.size)
console.log('Active contexts: ', sharedState.contextSourcesMap.size)
console.log('Content match entries', contentMatchCache.size)

and outputs:

Setting up new context...
Finding changed files: 8.926ms
Generate rules: 105.081ms
Build stylesheet: 3.188ms
Potential classes:  6042
Active contexts:  1
…

So on the last line, contentMatchCache is undefined

console.log('Content match entries', contentMatchCache.size)

---

All works fine if I disable debug mode or remove that line 👀

[octavezero]

Has anyone tried to use it with Jetbrains IDE's? Autocomplete is not working for me and I was wondering whether it has something to do with my config or some breaking changes which the IDE would need to fix

[adamwathan]

Definitely breaking changes to internals I'm afraid — we are finalizing a new built-in API for getting class completions though that hopefully they will be able to hook into.

[evanbarter]

Probably a dumb question, but here goes: is it possible to use the new JIT/CDN with an external stylesheet? Basically I've got some immutable HTML in a body tag, but I can conceivably change what's going on in the head. <style type="text/tailwindcss"> gets me really close, but in an ideal world <link rel="stylesheet" href="style-that-html.css" type="text/tailwindcss"> with a bunch of @applys would be :chefs_kiss:

[jessoliva]

Did you happen to find an answer to this? :)

[ivanchenhz]

Is that possible we are stuff like
class=“dark:(bg-red-800 text-white)”, to tailwind 3

Feels more readable and less typing 😄

Cannot wait for the performance improvement 👍

[luknl]

Thanks for the clear answer!
Then, does this problem also happen with projects using solutions like twind or twin.macro? Or it's a problem only with plain Tailwind.

[luknl]

Twind is not limited to strings as class names. Twind ships a compiler that runs when your app runs. This is unlike Tailwind, which generates CSS in a build step that is required before you run your app. This compiler is a function that is designed to interpret almost any form: strings, arrays, objects, template literals, or a mix of any of these.

https://twind.dev/handbook/grouping-syntax.html

[luknl]

Hey! Any updated on this?

[reinink]

@luknl See this Twitter thread from Adam: https://twitter.com/adamwathan/status/1461519820411789314

TLDR:

So the takeaway here is that although the grouped syntax looks like less code when you're authoring it, it actually creates both a bigger CSS file and a bigger HTML file in production, making it a very black and white performance anti-pattern.

[luknl]

Thank you, very clear answer!

[azunyuuuuuuu]

I quickly put the JIT CDN version as a demo on codepen and it's like magic. I used the default page of https://play.tailwindcss.com. It actually is much faster (for simple pages ofc) compared to the normal CDN version. There is no need to download and parse that huge css file and instead everything gets genereated by the new ✨ bits.

Link here: https://codepen.io/azunyuuuuuuu/pen/dyzpbzy

[mamunonweb]

After replacing gray with other colors, next time when I'm commenting or removing it, it still shows the previous color (pink) instead of the default color (gray)

Is this something?

[oben01]

Thank u for this great release.
Is Tailwindcss intellij plugin is compatible with this version ? (I cannot get autocompletion with the version : 203.6682.122)

[shmshd]

I believe Tailwindcss Intellij plugin is built by Jetbrain. So, update should be from them if not compatible.

[surjithctly]

Add a warning to remove mode: "jit" from the config.

As per my understanding, v3 uses JIT CDN by default, and a lot of folks including me are already using mode: "jit" in the config. Since it's no longer needed, a warning would have been great, so I don't forget it on multiple projects.

[NovusOpus]

Not JIT CDN but JIT Engine, JIT CDN is another feature, and note:

The Just-in-Time CDN is intended for development purposes only, and should not be used in production.

Edit:
Also a warning for people who have: purge: [], instead of the new updated content: [] configuration.
Update: There's already a warning for using purge: [], instead of the new content: [],

Although "The purge/content options have changed in Tailwind CSS v3.0" it's not very clear for some users, as you can see in new discussions, so maybe make it more straightforward like:

warn - The purge option is being replaced by content in Tailwind CSS v3.0.
warn - Please update your configuration file to eliminate this warning.

[shmshd]

In v2 there is an option to enable or disable purging (enabled: true|false). How is this with v3's content? I need to purge on production and not purge at dev build. Am I missing some other change?

[dcastil]

The JIT compiler is enabled by default in v3, so there is no need to purge anything. Tailwind just creates all the classes which it finds in your project.

[ddiabla]

So... HTML-only users (no framework) can use v3-alpha???

[adamwathan]

You can use it with anything 👍🏻

[DevZiya]

react js tailwind I did as css documentation did but it didn't work.
It would be great if you could make a short video about setting up React js and upload it to YouTube.