PX to Tailwind converter

Designers hand over pixels, Tailwind wants scale steps, and occasionally the pixel value you’ve been given has no utility at all. This handles all three situations.

How the spacing scale works

Every spacing utility you use, p-4 and gap-2 and mt-8 and w-64, is a multiple of one number. That number defaults to 0.25rem, which is 4px at the browser’s default root size. So p-4 works out to 4 × 4px = 16px, and gap-2 is 8px.

One multiplier, and that’s the entire system. Once “the number in the class is quarters of a rem” is in your head, most of the scale stops needing a lookup at all.

What v4 changed

This is where people who learned the scale on v3 get tripped up.

Spacing in v3 was a fixed lookup table. p-7 existed and p-13 didn’t. A design calling for 52px meant either adding a value to tailwind.config.js or writing an arbitrary value, because the class was never generated in the first place.

v4 derives the scale from a single theme variable:

@theme {
  --spacing: 0.25rem;
}

Utilities are generated on demand now as multiples of that variable, so p-13 and gap-29 and mt-52 are all real classes that need no configuration. In practice: any whole multiple of 4px has a utility. The converter assumes v4. If you’re still on v3, treat anything past the old table as “needs config”.

When there genuinely isn’t a class

Two situations produce nothing. Either the value isn’t a multiple of your spacing unit (13px doesn’t divide by 4), or you’ve landed between the half-steps. Tailwind keeps 0.5, 1.5, 2.5 and 3.5 from the old scale, which is 2px, 6px, 10px and 14px, but nothing finer.

Either way the answer is an arbitrary value like p-[13px]. That’s a supported escape hatch, not a code smell, and it compiles to exactly the CSS a custom scale entry would have produced.

The judgement call is how often you’re reaching for it. One or two in a component is nothing. Ten is your design system and your spacing unit disagreeing with each other, and the fix there is changing --spacing rather than escaping it over and over.

Changing the spacing unit

Design systems built on an 8-point grid can just move the basis:

@theme {
  --spacing: 0.5rem; /* 8px */
}

p-1 is 8px now and p-4 is 32px. Set the converter’s basis field to match and it’ll follow your theme instead of the default.

Worth knowing before you do it: this shifts every spacing utility at once, including a few you probably weren’t thinking about. space-y-*, inset-*, translate-* and the numeric w-*/h-* steps all come off the same variable.

Not everything numeric is on this scale

text-lg isn’t lg multiplied by anything. Font sizes, border radii, line heights and breakpoints all have their own scales, so converting a pixel font size here gives you a spacing step that means nothing in text-*.

The utilities that do use --spacing: padding, margin, gap, width, height, size, inset, translate, space-between, scroll margin and scroll padding. If the class takes a bare number and represents a distance, it’s on the scale.

Negative values go on the class rather than the number, so -mt-4 and not mt--4. The converter gives you the positive step and you add the hyphen. Arbitrary negatives follow the same shape: -mt-[13px].

Two failure modes worth knowing

p-4 isn’t always 16px. It’s 16px when the root font size is 16px, which is just the default. --spacing is in rem, so a reader who has increased their browser text size gets proportionally larger spacing. That’s the correct behaviour, and switching the scale to px to “fix” it would break the thing that makes it accessible.

A class assembled at runtime will never exist. Tailwind scans your source as plain text, so the class has to appear as a complete literal string somewhere. Write `p-[${n}px]` and you’ll get nothing, every time, with no error to tell you why. Either write the full class or map your values to whole class names.