Tailwind CSS v4 support

[dcastil]

Tailwind CSS v4 will be released next week: https://x.com/adamwathan/status/1879856208552845570.

I expect to add support for it a few days after the Tailwind CSS v4 release. Most probably it will be a new major tailwind-merge version with the only breaking change being that it supports Tailwind CSS v4 instead of v3.

Feel free to subscribe to this issue to get notified when support for Tailwind CSS v4 lands.

Some additional info in #468.

Changes to check

✅ Tailwind CSS v4 annnouncement

Tailwind CSS v4 annnouncement

• New high-performance engine
• Designed for the modern web
• Simplified installation
• First-party Vite plugin
• Automatic content detection
• Built-in import support
• CSS-first configuration
• CSS theme variables
• Dynamic utility values and variants
• Modernized P3 color palette
• Container queries
• New 3D transform utilities
  • transform-style
  • rotate
  • perspective
  • perspective-origin
• Expanded gradient APIs
  • Linear gradient angles
  • Gradient interpolation modifiers
  • Conic and radial gradients
• @starting-style support
• not-* variant
• Even more new utilities and variants
  • inset-shadow-* and inset-ring-*
  • field-sizing
  • color-scheme
  • font-stretch
  • inert
  • nth-*
  • in-*
  • :popover-open
  • descendant variant

✅ Upgrade guide

Upgrade guide

• Removed @tailwind directives
• Removed deprecated utilities
• Renamed utilities
  • Updated shadow, radius, and blur scales
  • Renamed outline utility
  • Default ring width change
• Container configuration
• Preflight changes
  • New default border color
  • New default placeholder color
• Adding custom utilities
• Variant stacking order
• Variables in arbitrary values
• Hover styles on mobile
• Disabling core plugins
• Using the theme() function
• Using a JavaScript config file
• Theme values in JavaScript

✅ Utility schemas

• Layout
  • aspect-ratio
  • columns
  • break-after
  • break-before
  • break-inside
  • box-decoration-break
  • box-sizing
  • display
  • float
  • clear
  • isolation
  • object-fit
  • object-position
  • overflow
  • overscroll-behavior
  • position
  • top / right / bottom / left
  • visibility
  • z-index
• Flexbox and grid
  • flex-basis
  • flex-direction
  • flex-wrap
  • flex
  • flex-grow
  • flex-shrink
  • order
  • grid-template-columns
  • grid-column
  • grid-template-rows
  • grid-row
  • grid-auto-flow
  • grid-auto-columns
  • grid-auto-rows
  • gap
  • justify-content
  • justify-items
  • justify-self
  • align-content
  • align-items
  • align-self
  • place-content
  • place-items
  • place-self
• Spacing
  • padding
  • margin
• Sizing
  • width
  • min-width
  • max-width
  • height
  • min-height
  • max-height
• Typography
  • font-family
  • font-size
  • font-smoothing
  • font-style
  • font-weight
  • font-stretch
  • font-variant-numeric
  • letter-spacing
  • line-clamp
  • line-height
  • list-style-image
  • list-style-position
  • list-style-type
  • text-align
  • color
  • text-decoration-line
  • text-decoration-color
  • text-decoration-style
  • text-decoration-thickness
  • text-underline-offset
  • text-transform
  • text-overflow
  • text-wrap
  • text-indent
  • vertical-align
  • white-space
  • word-break
  • hyphens
  • content
• Backgrounds
  • background-attachment
  • background-clip
  • background-color
  • background-image
  • background-origin
  • background-position
  • background-repeat
  • background-size
• Borders
  • border-radius
  • border-width
  • border-color
  • border-style
  • outline-width
  • outline-color
  • outline-style
  • outline-offset
• Effects
  • box-shadow
  • opacity
  • mix-blend-mode
  • background-blend-mode
• Filters
  • filter
    • blur
    • brightness
    • contrast
    • drop-shadow
    • grayscale
    • hue-rotate
    • invert
    • saturate
    • sepia
  • backdrop-filter
    • blur
    • brightness
    • contrast
    • grayscale
    • hue-rotate
    • invert
    • opacity
    • saturate
    • sepia
• Tables
  • border-collapse
  • border-spacing
  • table-layout
  • caption-side
• Transitions & Animation
  • transition-property
  • transition-behavior
  • transition-duration
  • transition-timing-function
  • transition-delay
  • animation
• Transforms
  • backface-visibility
  • perspective
  • perspective-origin
  • rotate
  • scale
  • skew
  • transform
  • transform-origin
  • transform-style
  • translate
• Interactivity
  • accent-color
  • appearance
  • caret-color
  • color-scheme
  • cursor
  • field-sizing
  • pointer-events
  • resize
  • scroll-behavior
  • scroll-margin
  • scroll-padding
  • scroll-snap-align
  • scroll-snap-stop
  • scroll-snap-type
  • touch-action
  • user-select
  • will-change
• SVG
  • fill
  • stroke
  • stroke-width
• Accessibility
  • forced-color-adjust

✅ Syntax changes

#513 (comment)

• Important modifier is at the end now (but beginning supported too for BC)
• New shorthand syntax for variables as arbitrary values
• Respect variant order from Tailwind CSS when not reorderable Tailwind CSS v4 support #513 (comment)
• Prefixes look like variants, and always come first
• Arbitrary variants support HTML elements now and don't always require an &

Issues discovered

• shadow class missing in v4 docs tailwindlabs/tailwindcss.com#1985
• Inset ring color classes have incorrect names in API table tailwindlabs/tailwindcss.com#1988
• Add missing arbitrary value option to flex API table tailwindlabs/tailwindcss.com#2002
• Issues with content in v4 API tables tailwindlabs/tailwindcss.com#2027
• [v4] CSS bundle bloated when using @tailwindcss/vite and tailwind-merge tailwindlabs/tailwindcss#15722

[dcastil]

@adamwathan Are there any syntax-related changes in Tailwind CSS v4 that I should be aware of that weren't mentioned in the announcement post or upgrade guide?

[Bricklou]

Maybe weird selectors like this might cause troubles 🤔

https://tailwindcss.com/docs/styling-with-utility-classes#complex-selectors
https://tailwindcss.com/docs/hover-focus-and-other-states#has
https://tailwindcss.com/docs/hover-focus-and-other-states#pseudo-elements
https://tailwindcss.com/docs/hover-focus-and-other-states#attribute-selectors

[adamwathan]

@adamwathan Are there any syntax-related changes in Tailwind CSS v4 that I should be aware of that weren't mentioned in the announcement post or upgrade guide?

I think the only syntax-ish changes are these:

• Important modifier is at the end now (but beginning supported too for BC)
  • !underline → underline!
• New shorthand syntax for variables as arbitrary values
  • w-[--my-var] → w-(--my-var)
• Variants are applied in reverse order from v3
  • before:*:underline → *:before:underline
• Prefixes look like variants, and always come first
  • dark:lg:tw-underline → tw:dark:lg:tw-underline
• Arbitrary variants support HTML elements now and don't always require an &
  • [p]:underline adds an underline if the element is a p tag

I think that's everything 👍

[dcastil]

@adamwathan awesome, thanks for the list!

I wonder: Do you have some code in the Tailwind CSS codebase that checks whether variants are reorderable? E.g. in hover:focus:x the order doesn't matter but in focus:before:hover:x it does.

tailwind-merge sorts variants internally (between arbitrary variants) to allow better deduplication, but maybe it isn't feasible anymore to do that.

[adamwathan]

@dcastil I think there is some stuff for that sort of thing here:

https://github.com/tailwindlabs/tailwindcss/blob/next/packages/%40tailwindcss-upgrade/src/template/codemods/variant-order.ts

Here's the tests which explain what it changes and doesn't change:

https://github.com/tailwindlabs/tailwindcss/blob/next/packages/%40tailwindcss-upgrade/src/template/codemods/variant-order.test.ts