How to define custom Tailwind variants for media breakpoints?

Question

I am working on migrating a code base from Styled Components to Tailwind v4.

To avoid introducing breaking changes to our design, I want to continue using the same media breakpoints and media queries, which are different from the default values in Tailwind

From the docs on adding custom variants, I can see that I can use the @custom-variant directive.

But, can I use that for defining custom media breakpoints?

e.g. like this:

@custom-variant max-xs (@media (max-width: 375px));
@custom-variant max-sm (@media (max-width: 576px));
@custom-variant max-md (@media (max-width: 768px));

Is this valid Tailwind syntax?

If not, how can I create custom media queries in Tailwind v4?

I wouldn't normally use it that way. The documented breakpoint and max-breakpoint approach is much more consistent, and both breakpoints become automatically available through the namespace declaration. The only difference is that the relation changes from <= to < when use max-{breakpoint}. See generated CSS: play.tailwindcss.com/MryeIVxhHc?file=css — rozsazoltan
– rozsazoltan, Commented Nov 3 at 17:54

Wongjn · Accepted Answer · 2025-11-03 17:39:49Z

For breakpoints, you'd want to use the --breakpoint-* namespace in @theme:

@theme {
  --breakpoint-xs: 375px;
  --breakpoint-sm: 576px;
  --breakpoint-md: 768px;
}

You will get max-* variants generated for you automatically from these values.

Also bear in mind:

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.

So if you want to keep your pixel definitions, you'd want to disable Tailwind's default breakpoints:

@theme {
  --breakpoint-*: initial;
  --breakpoint-xs: 375px;
  --breakpoint-sm: 576px;
  --breakpoint-md: 768px;
}

Or convert yours to rem:

@theme {
  --breakpoint-xs: 23.4375rem;
  --breakpoint-sm: 36rem;
  --breakpoint-md: 48rem;
}

rozsazoltan · Accepted Answer · 2025-11-03 17:39:49Z

Use default breakpoint system

I see that you'd like to define your breakpoints using pixel-based values. It's important to note that TailwindCSS uses rem-based breakpoints by default, so it's recommended to completely disable them using the following:

@theme {
  --breakpoint-*: initial;
}

Basically, you can define a custom breakpoint using the --breakpoint-* namespace, but it strictly follows the mobile-first approach:

How to use custom breakpoints

@theme {
  --breakpoint-*: initial;
  --breakpoint-xs: 375px;
  --breakpoint-sm: 576px;
  --breakpoint-md: 768px;
}

For these, the corresponding max-{breakpoint} pairs you mentioned are automatically generated.

Breakpoint range (new from v4)

It's important to note that these max breakpoints use the < relation by default, not <=.

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@theme {
  --breakpoint-*: initial;
  --breakpoint-xs: 375px;
  --breakpoint-sm: 576px;
  --breakpoint-md: 768px;
}
</style>

<div class="size-32 max-md:bg-amber-500 bg-sky-500"></div>

Declare custom variants

A completely custom variant that behaves like a breakpoint should be created in a similar way to how you attempted:

How to make TailwindCSS v4 desktop-first breakpoints

So what you wrote is valid, but it's not the default approach.

Collectives™ on Stack Overflow

How to define custom Tailwind variants for media breakpoints?

2 Answers 2

Comments

Use default breakpoint system

Declare custom variants

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Use default breakpoint system

Declare custom variants

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related