Skip to content

Commit 863445d

Browse files
adamwathanadamwathan
committed
WIP
1 parent 8f50cc1 commit 863445d

File tree

1 file changed

+240
-2
lines changed

1 file changed

+240
-2
lines changed

‎src/pages/docs/v4-beta.mdx

Lines changed: 240 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1473,36 +1473,274 @@ If you're just using the default theme, you can import `"tailwindcss/theme"` dir
14731473

14741474
---
14751475

1476-
## Breaking changes
1476+
## Changes from v3
1477+
1478+
Tailwind CSS v4.0 is a new major version of the framework, and while we strive to preserve backward compatibility as much as possible, there are several breaking changes we've had to make to make the improvements we wanted to make for the new release.
1479+
1480+
To make the upgrade as painless as possible, we've built a really awesome migration tool that will automate basically all of these changes for you.
1481+
1482+
To upgrade your project automatically, run the upgrade tool from your project root on the command-line:
1483+
1484+
```bash {{ filename: 'Terminal' }}
1485+
$ npx @tailwindcss/upgrade@next
1486+
```
1487+
1488+
Once it's done, review all of the changes and test your project to make sure everything is working as expected, and with any luck you'll be off to the races.
1489+
1490+
But here's a list of all of the changes in detail in case you run into issues using the migration tool.
14771491

14781492
### Dependency changes
14791493

1494+
#### Using PostCSS
1495+
1496+
In Tailwind CSS v3, the `tailwindcss` package was a PostCSS plugin, but in v4.0 the PostCSS plugin lives in a dedicated `@tailwindcss/postcss` package.
1497+
1498+
Tailwind CSS v4.0 also handles CSS imports and vendor prefixing for you, so you can remove `postcss-import` and `autoprefixer` if they are in your project:
1499+
1500+
```diff-js {{ filename: 'postcss.config.mjs' }}
1501+
export default {
1502+
plugins: {
1503+
- 'postcss-import': {},
1504+
- 'tailwindcss': {},
1505+
- 'autoprefixer': {},
1506+
+ '@tailwindcss/postcss': {},
1507+
},
1508+
};
1509+
```
1510+
1511+
#### Using Vite
1512+
1513+
If you're using Vite, we recommend migrating from the PostCSS plugin to [our new dedicated Vite plugin](#installing-with-vite):
1514+
1515+
```ts {{ filename: 'vite.config.ts' }}
1516+
import { defineConfig } from 'vite';
1517+
> import tailwindcss from '@tailwindcss/vite';
1518+
1519+
export default defineConfig({
1520+
plugins: [
1521+
> tailwindcss()
1522+
],
1523+
});
1524+
```
1525+
1526+
#### Using Tailwind CLI
1527+
1528+
In v4.0, Tailwind CLI lives in a dedicated `@tailwindcss/cli` package. Update any of your build commands to use the new package instead:
1529+
1530+
```diff
1531+
- npx tailwindcss -i input.css -o output.css
1532+
+ npx @tailwindcss/cli -i input.css -o output.css
1533+
```
1534+
14801535
### Removed \`@tailwind\` directives
14811536

1537+
In Tailwind CSS v4.0, you import Tailwind using a regular CSS `@import` statement, not using the `@tailwind` directives you used in v3:
1538+
1539+
```diff-css
1540+
- @tailwind base;
1541+
- @tailwind components;
1542+
- @tailwind utilities;
1543+
+ @import "tailwindcss";
1544+
```
1545+
14821546
### Removed deprecated utilities
14831547

1548+
We've removed any utilities that were deprecated in v3 and have been undocumented for several years. Here's a list of what's been removed along with the modern alternative:
1549+
1550+
| Deprecated | Replacement |
1551+
| --- | --- |
1552+
| `bg-opacity-*` | Use opacity modifiers like `bg-black/50` |
1553+
| `text-opacity-*` | Use opacity modifiers like `text-black/50` |
1554+
| `border-opacity-*` | Use opacity modifiers like `border-black/50` |
1555+
| `divide-opacity-*` | Use opacity modifiers like `divide-black/50` |
1556+
| `ring-opacity-*` | Use opacity modifiers like `ring-black/50` |
1557+
| `placeholder-opacity-*` | Use opacity modifiers like `placeholder-black/50` |
1558+
| `flex-shrink-*` | `shrink-*` |
1559+
| `flex-grow-*` | `grow-*` |
1560+
| `overflow-ellipses` | `text-ellipsis` |
1561+
| `decoration-slice` | `box-decoration-slice` |
1562+
| `decoration-clone` | `box-decoration-clone` |
1563+
14841564
### Configuring the \`container\` utility
14851565

1566+
In v3, the `container` utility had several configuration options like `center` and `padding` that no longer exist in v4.0. To customize the `container` utility in v4.0, extend it with `@utility`:
1567+
1568+
```css
1569+
@import "tailwindcss";
1570+
1571+
@utility container {
1572+
margin-inline: auto;
1573+
padding-inline: 2rem;
1574+
}
1575+
```
1576+
14861577
### Default shadow scale changes
14871578

1579+
We've shifted things around a bit in the default shadow scales to make sure every shadow utility has a named value.
1580+
1581+
To do this, we've renamed `shadow` to `shadow-sm`, `shadow-sm` to `shadow-xs`, `drop-shadow` to `drop-shadow-sm`, and `drop-shadow-sm` to `drop-shadow-xs`:
1582+
1583+
| v3 | v4 |
1584+
| ----------------- | ------------------ |
1585+
| `shadow-sm` | `shadow-xs` |
1586+
| `shadow` | `shadow-sm` |
1587+
| `drop-shadow-sm` | `drop-shadow-xs` |
1588+
| `drop-shadow` | `drop-shadow-sm` |
1589+
1590+
The `shadow` and `drop-shadow` utilities will still work for backward compatibility, but `shadow-sm` and `drop-shadow-sm` will look different in your project if you don't replace each instance with `shadow-xs` and `drop-shadow-xs` instead.
1591+
14881592
### Default blur scale changes
14891593

1594+
We've shifted things around a bit in the default blur scale to make sure every blur utility has a named value.
1595+
1596+
To do this, we've renamed `blur` to `blur-sm`, and `blur-sm` to `blur-xs`:
1597+
1598+
| v3 | v4 |
1599+
| ----------------- | ------------------ |
1600+
| `blur-sm` | `blur-xs` |
1601+
| `blur` | `blur-sm` |
1602+
1603+
The `blur` utility will still work for backward compatibility, but `blur-sm` will look different in your project if you don't replace each instance with `blur-xs` instead.
1604+
14901605
### Default radius scale changes
14911606

1607+
We've shifted things around a bit in the default border radius scale to make sure every border radius utility has a named value.
1608+
1609+
To do this, we've renamed `rounded` to `rounded-sm`, and `rounded-sm` to `rounded-xs`:
1610+
1611+
| v3 | v4 |
1612+
| ----------------- | ------------------ |
1613+
| `rounded-sm` | `rounded-xs` |
1614+
| `rounded` | `rounded-sm` |
1615+
1616+
The `rounded` utility will still work for backward compatibility, but `rounded-sm` will look different in your project if you don't replace each instance with `rounded-xs` instead.
1617+
14921618
### Default border color change
14931619

1620+
In v3, borders used your configured `gray-200` color by default. We've updated this in v4 to be just `currentColor`, which matches the default behavior of all browsers.
1621+
1622+
To update your project for this change, make sure anywhere you're using a border color utility anywhere you're using the `border` utility, or add these lines of CSS to your project to preserve the v3 behavior:
1623+
1624+
```css
1625+
@import "tailwindcss";
1626+
1627+
> @layer base {
1628+
> *,
1629+
> ::after,
1630+
> ::before,
1631+
> ::backdrop,
1632+
> ::file-selector-button {
1633+
> border-color: var(--color-gray-200, currentColor);
1634+
> }
1635+
> }
1636+
```
1637+
14941638
### Default ring width change
14951639

1640+
In v3, the `ring` utility added a 3px ring. We've changed this in v4 to be 1px to make it consistent with borders and outlines.
1641+
1642+
To update your project for this change, replace any usage of `ring` with `ring-3`:
1643+
1644+
```diff-html
1645+
- <div class="**ring** ring-blue-500">
1646+
+ <div class="**ring-3** ring-blue-500">
1647+
<!-- ... -->
1648+
</div>
1649+
```
1650+
14961651
### Default placeholder change
14971652

1653+
In v3, placeholder text used your configured `gray-400` color by default. We've simplified this in v4 to just use the current text color at 50% opacity.
1654+
1655+
You probably won't even notice this change (it might even make your project look better), but if you want to preserve the v3 behavior, add this CSS to your project:
1656+
1657+
```css
1658+
@import "tailwindcss";
1659+
1660+
> @layer base {
1661+
> input::placeholder,
1662+
> textarea::placeholder {
1663+
> color: theme(--color-gray-400);
1664+
> }
1665+
> }
1666+
```
1667+
14981668
### \`outline-none\` to \`outline-hidden\`
14991669

1670+
In v3, the `outline-none` utility was actually a complex class that didn't just set `outline-style: none`:
1671+
1672+
```css
1673+
/* v3 */
1674+
.outline-none {
1675+
outline: 2px solid transparent;
1676+
outline-offset: 2px;
1677+
}
1678+
```
1679+
1680+
What it really did was add an invisible 2px outline that would still show up in forced colors mode for accessibility reasons.
1681+
1682+
We've simplified this in v4.0 and now `outline-none` just sets `outline-style: none` like you'd expect:
1683+
1684+
```css
1685+
/* v4 */
1686+
.outline-none {
1687+
outline-style: none;
1688+
}
1689+
```
1690+
1691+
We've added a new `outline-hidden` utility that does what `outline-none` did in v3, since it's still a very useful feature.
1692+
1693+
To update your project for this change, replace any use of `outline-none` with `outline-hidden`, unless you really do want `outline-style: none`:
1694+
1695+
```diff-html
1696+
- <input class="**focus:outline-none**">
1697+
+ <input class="**focus:outline-hidden**">
1698+
```
1699+
15001700
### Adding custom utilities
15011701

1502-
### Simplified \`@apply\` behavior
1702+
In v3, any custom classes you defined within `@layer utilities` would get picked up by Tailwind as a true utility class and would automatically work with variants like `hover`, `focus`, or `lg`.
1703+
1704+
In v4.0 we are using native cascade layers and no longer hijacking the `@layer` at-rule, so we've introduced the `@utility` API as a replacement:
1705+
1706+
```diff-css
1707+
- @layer utilities {
1708+
- .tab-4 {
1709+
- tab-size: 4;
1710+
- }
1711+
- }
1712+
+ @utility tab-4 {
1713+
+ tab-size: 4;
1714+
+ }
1715+
```
1716+
1717+
Custom utilities must be a single class name in v4.0 and not a complex selector. If your custom utility is more complex than a single class name, use nesting to define the utility:
1718+
1719+
```css
1720+
@utility scrollbar-hidden {
1721+
&::-webkit-scrollbar {
1722+
display: none;
1723+
}
1724+
}
1725+
```
15031726

15041727
### Stacking order-sensitive variants
15051728

1729+
In v3, stacked variants were applied from right to left, but in v4 we've updated them to apply left to right to look more like CSS syntax.
1730+
1731+
To update your project for this change, reverse the order of any order-sensitive stacked variants in your project:
1732+
1733+
```diff-html
1734+
- <ul class="py-4 first:*:pt-0 last:*:pb-0">
1735+
+ <ul class="py-4 *:first:pt-0 *:first:pb-0">
1736+
<li>One</li>
1737+
<li>Two</li>
1738+
<li>Three</li>
1739+
</ul>
1740+
```
1741+
1742+
You likely have very few of these if any — the direct child variant (`*`) and any typography plugin variants (`prose-headings`) are the most likely ones you might be using, and even then it's only if you've stacked them with other variants.
1743+
15061744
### CSS variables in arbitrary values
15071745

15081746
### Referencing theme values in JS

0 commit comments

Comments
 (0)