How to add and use custom breakpoint tailwindcss v4

I'm trying to define a custom breakpoint in the latest version of taildwindcss. Since this version doesn't require config file anymore I've tried to define it in the @theme:

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@import "tailwindcss";

@theme {
  /* Define breakpoints for responsive design */
  --breakpoint-xxl: 1380px;
}
</style>

<div class="flex flex-col justify-center xxl:flex-row xxl:justify-start xxl:bg-red-900 gap-3">
  <h1>Hello World</h1>
</div>

But when I run it, it works for the bg color but not for the flex-direction.

Solution

Note that it's important to always use the same unit for defining your breakpoints or the generated utilities may be sorted in an unexpected order, causing breakpoint classes to override each other in unexpected ways.

Tailwind uses rem for the default breakpoints, so if you are adding additional breakpoints to the defaults, make sure you use rem as well.

Source: Customizing your theme - TailwindCSS v4 Docs

By default, dynamic rem units are used for defining all breakpoints. The advantage of rem is that it ensures consistent scaling between breakpoints. Fixed px breakpoints - like the one you're using - are not ideal because they are static. For example, 64rem can actually be larger or smaller depending on the root font size of the page.

The recommendation is to define all breakpoints using rem units. That way, xxl will always come after xl as expected.

In terms of order, Tailwind CSS treats breakpoints defined in px as weaker and places them before those defined in rem.

Which one is larger - 1380px or 64rem? There's no fixed answer to this question at build time, because rem can vary depending on the base font size. You might say that you're not going to change it, but any external influence - such as user settings or styles - could alter the base font size. As a result, 1380px could end up being larger than 64rem, or smaller.

Solution #1

Instead, calculate the ideal xxl size for your use case in rem.

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@theme {
  /* 86.25rem is definitely larger than 64rem, so it will be placed in the correct order in the compiled CSS */
  --breakpoint-xxl: 86.25rem; /* 64rem = 1024xp --> 1380px = 86.25rem */
}
</style>

<div class="flex lg:flex-col lg:bg-red-500 xxl:flex-row xxl:bg-green-500">
  <p>Hello</p>
  <p>World</p>
</div>

In this case, if you define a value greater than lg's 64rem, the xxl: breakpoint will automatically become stronger than the lg: breakpoint.

Solution #2

Or if you absolutely want to stick with px, then redefine all the default breakpoints as well using the table below:

Removing default breakpoints - TailwindCSS v4 Docs
Responsive design - TailwindCSS v4 Docs

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@theme {
  /* cleared everything with the initial value, but I manually entered everything from the documentation table */
  --breakpoint-*: initial;
  /* can set the breakpoints you want to keep */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-xxl: 1380px; /* added your custom breakpoint here */
  --breakpoint-2xl: 1536px;
}
</style>

<div class="flex lg:flex-col lg:bg-red-500 xxl:flex-row xxl:bg-green-500">
  <p>Hello</p>
  <p>World</p>
</div>

TailwindCSS v4 Playground with only px breakpoints - Expected result

This will ensure the order is correct again, as 1380px will always be larger than 1024px, so it will be in the proper order in the compiled CSS.