Mobile responsiveness & Container padding in React Email

[DoniyorLatipov]

First off — if anyone can point me to solid documentation on responsiveness in React Email, I'd really appreciate it. Everything below is just what I pieced together on my own, because I couldn't find anything more useful.

Adding responsiveness

Here's the Tailwind config I've been using. These are just the values I found convenient — feel free to change them:

const tailwindConfig = {
  presets: [pixelBasedPreset],
  theme: {
    screens: {
      sm: { max: '600px' },
    },
  },
}

From there you use it exactly like normal Tailwind responsive classes (e.g. sm:p-2).

Problems I ran into

1. On export, the email ends up with range-syntax media queries (@media (600px >= width)), which aren't handled reliably across email clients.
2. On top of that, a separate media query gets generated for every class. So a fully responsive layout can easily end up with 10+ media queries, which also bloats the file size.

Solution

Merge all of those generated queries into a single @media (max-width: 600px) block.

I wrote a small script — post-export-media-fix.mjs — that does exactly this. You can run it as part of npm run export.

👉 Gist / script link

A side effect of this approach

The sm: padding on the Container component behaves unexpectedly.

The regular padding classes get inherited by the inner <td>, but the sm: classes stay on the outer <table>. Because of that, when you actually want to reduce padding on phones, you can end up increasing it instead — the base padding (on the <td>) and the sm: padding (on the <table>) stack on top of each other.

My workaround

Manually move the sm_p-* class off the <table> and onto the child <td>.

Bonus: stacking columns on mobile

This one's also handy — a utility class that turns a row into a stacked column. Apply it to each <td> you want to stack:

@media only screen and (max-width: 600px) {
  .col-stack {
    display: block !important;
    width: 100% !important;
    max-width: 100% !important;
    padding-left: 0 !important;
  }
}

---

Thanks for reading! Any feedback is very welcome. 🙌

P.S. Another side effect — still unresolved

Because the correct output depends on the post-export script, the built-in test-email feature becomes unreliable. React Email sends the test message using the raw export output — i.e. the HTML before my script has finalized it — so the email that actually lands in the inbox still has the scattered, un-merged media queries and doesn't render the way the finalized version does. Right now the only way I trust a preview is to check HTML that has already been through the script, but I haven't found a clean way to make the built-in test-send respect that step. Ideas welcome 🧐