Customized plain text render to hide select elements

[djfarrelly]

Goals

1. When rendering the email as plain text, I want to hide certain elements in addition to images, for example links that wrap images (like a company logo).

Background

The company logo in our email template is hyperlinked to our website and rendering our emails to plaintext gives us:

https://www.inngest.com?ref=email-invite

Hi there,

You've been invited to join your team...

Email code:

<a
  href="https://www.inngest.com?ref=email-invite"
  target="_blank"
>
  <Img
    className="mx-auto"
    src={`${imageUrl}logo-on-white.png`}
    alt="Inngest"
    width={200}
    height={(200 / 220) * 90}
  />
</a>

What I want is to hide that link that wraps our logo:

Hi there,

You've been invited to join your team...

Proposal

This could be solved w/ a special classname or data attribute that can be passed which filter uses in it's rules to remove:

https://github.com/resendlabs/react-email/blob/d158ad77e3798808b4efbd322b618922da12529e/packages/render/src/render.ts#L31-L34

Suggested options

1. Use a dataPlainText={false} (or similar) attribute in renderAsPlainText
2. Use a special class __react-email-plaintext-skip to hide elements in renderAsPlainText
3. Create a new <PlainText hide={true}>{children}</PlainText> or similar component that can wrap elements to hide on plaintext renders
4. Create a new <Visible plaintext>{children}</Visible> / <Visible html>{children}</Visible> / <Visible html plaintext>{children}</Visible> that can wrap elements and the user can explicitly set if they want something to render on one or the other.

Current workaround

My current hack is to use __react-email-preview, although it's not good HTML to have multiples of the same id attr.

<a
  href="https://www.inngest.com?ref=email-invite"
  target="_blank"
  id={hiddenOnPlainTextId}
>
  <Img
    className="mx-auto"
    src={`${imageUrl}logo-on-white.png`}
    alt="Inngest"
    width={200}
    height={(200 / 220) * 90}
  />
</a>

[bliepp]

So, I'm currently looking for the exact same feature. With the code snippet you have linked it seems to be a one line addition (now in here). Just adding a class that hides the element in plainText mode. I've searched for it, but didn't find a PR. Did you open one yet?

[thena-seer]

Here is a PR: #1922

[gabrielmfern]

Here's a better idea: we can simply store the rendering options in some global variable, and return it in a hook-like function useRenderingOptions, that you can use like

import { useRenderingOptions } from '@react-email/render';

function MyEmail() {
  const renderingOptions = useRenderingOptions();
  
  if (renderingOptions.plainText) {
    return 'This is the text according to what I would prefer';
  }

  return <a href="https://react.email">This is the text according to what I would prefer</a>;
}

@thena-seer I see you made a PR with the other proposal, if you'd like to contribute an implementation of this, feel free to use this instead. I had this planned a while back from a discussion I had on Discord.

[thena-seer]

Closed the other PR and created a new PR #1926

[emiliosheinz]

Hey @gabrielmfern, @thena-seer, @djfarrelly, and @bliepp

Since using Context can break server-side rendering, and global variables don’t work well for parallel render calls with different option sets, I propose an alternative: pass a reactEmailRenderOptions (or similar) prop down to components during rendering.

Why this approach?
The goal is to give developers a clean, React-idiomatic way to control how components behave in different contexts (HTML vs. plain text) without relying on global variables, special class names, or attributes.

Key benefits:

• Native React pattern – Works in all environments (Node, Edge, browser) and avoids environment-specific global state.
• Supports deeply nested components – Options are naturally available anywhere in the component tree through prop drilling, eliminating the need for CSS selectors or duplicated IDs. Developers who prefer can also wrap them in a React Context or store them in a global variable for even easier access.
• Explicit and flexible – Developers can make rendering decisions directly in their components:

function Logo({ reactEmailRenderOptions }) {
  if (reactEmailRenderOptions?.plainText) return null;
  return <img src="logo.png" alt="Logo" />;
}

• Easy to test – Since it’s just a prop, you can pass different values in tests to verify HTML vs. plain text output without extra setup.

This keeps the solution explicit, portable, and testable, while staying consistent with how React normally handles data flow.

Here is a draft PR for it: #2417

Please, let me know your thoughts :)

[bliepp]

Okay I just played a bit with your PR and works like a charm. I really like the basic idea of "infusing" the render options into a component using a withAdditionalProps function (although I think the name is bad as it implies general purpose property addition, while it is really only for additional render options). There are a few things I really don't like, though:

1. Adding it implicitly while rendering might be confusing. It's not as verbose as explicitly declaring the use of rendering options.
2. This approach requires prop drilling. It might not be as much of a problem, as I really hope most React Email projects are not too deeply nested, but I really dislike prop drilling in general. It is very error prone, easy to forget when passing from parent to child, and unnecessarily bloating the code (especially with TypeScript).

This might be the only reasonable solution (considering the concerns you have raised) and I'd rather have that solution than none. Is there maybe a way to expose a function, that applies withAdditionalProps to components selectively? What I mean is basically a pattern similar to the forwardRef function of React < 19:

function MyComponent({renderOptions}) {
    return <>
        {renderOptions?.plainText && <Example />}
    </>;
}

export default forwardRenderOptions(MyComponent);

(It might not be possible, though, and I'd totally understand that.)

Also, maybe consider renaming that prop to something shorter (like just renderOptions). There are no naming collisions to be expected, are there?

All in all: really nice solution with maybe a few changes that would make it perfect in my opinion.

[emiliosheinz]

Thank you for your feedback @bliepp

1. About the withAdditionalProps function naming and purpose — I'll refactor it so that any props can be passed to the function, or simply rename the function so the naming better represents the function's purpose.
2. Adding it implicitly while rendering might be confusing. It's not as verbose as explicitly declaring the use of rendering options. — I agree, but, at the same time, if well documented, I feel like it is a solid approach.
3. This approach requires prop drilling — Not really, one could create a context, or whatever, inside the Email Template, to expose the props to inner components without having to explicitly pass the props down. But yeah, that is up to the user.
4. About the forwardRenderOptions — I'll explore that option and come back to you with my findings
5. About the reactEmailRenderOptions naming — I'm totally open to suggestions, I tried to make it as explicit as possible to say that these are render options coming from React Email. But I also like the idea of simplifying it.

[emiliosheinz]

withRenderOptions seems like a viable approach. Please check the PR linked above for more details, but in short, users would only need to:

type TemplateWithOptionsProps = { id: string };

const TemplateWithOptions = withRenderOptions<TemplateWithOptionsProps>(
  (props) => {
    return <>{props.reactEmailRenderOptions?.plainText && <Example />}</>;
  },
);

I also prefer this approach over our previous solution, as it provides a cleaner and more straightforward way for users to pass options without the drawbacks we had before. And it is fully type safe:

Note: the code in the PR is just a proposal and might still need to be polished

[emiliosheinz]

Just FYI, I’ve refined and pushed the final version of the implementation, and it’s ready for review. Feel free to take a look and share your thoughts: #2417

[aprendendofelipe]

Hi everyone, thanks for all the great input on this discussion. I've been following along and wanted to share an idea.

It seems like we might be leaning towards solutions that are more complex than necessary. I took a look at the underlying implementation and noticed that react-email already uses html-to-text with a custom setting that automatically omits any element with the data-skip-in-text={true} selector.

Perhaps the simplest path forward would be to just document this feature. We could also take this opportunity to decide if data-skip-in-text is the best name for a public API, or if something more intuitive would be better, for instance, a selector like data-html-only.

Regarding the other proposals:

• The useRenderingOptions hook was a very interesting idea, but now that the plainText prop is deprecated in favor of the toPlainText function, it might not be as relevant.
• For the solutions based on prop drilling, they seem to introduce an opinionated pattern that doesn't provide a significant advantage over what consumers can already implement on their own if needed.

In short, I'm proposing we solve this by documenting the selector that's already available.

However, I'm happy to help implement whatever path we decide is best. If we feel the useRenderingOptions hook is still the right direction, I'd be glad to try implementing it, taking into account the lessons learned from previous PRs (like #1926 and #2417).

What do you all think of this approach?

[emiliosheinz]

Thank you for your feedback @aprendendofelipe.

When you mention that “solutions based on prop drilling introduce an opinionated pattern that doesn’t provide a significant advantage over what consumers can already implement on their own”, could you expand on that? I want to make sure I fully understand your perspective. When developing withRenderOptions, I considered most of the points you raised, and my main goal was to find a good balance between complexity, ease of use, and alignment with React standards and best practices. Here are a couple of things worth noting:

• Flexibility vs. simplicity: While using data-skip-in-text={true} is indeed the simplest path forward, it’s not as flexible as having a prop in your component, for example. I believe that the original intention behind the useRenderingOptions hook was to give developers a more declarative way to control rendering behavior directly at the component level, rather than relying solely on DOM attributes, to hide or show elements.

• Cross-environment concerns: Introducing something like useRenderingOptions would likely require some internal “magic” to work seamlessly across different rendering environments (server, client, edge, etc.). This adds a layer of complexity that could be tricky to maintain and might result in inconsistent behavior if not carefully handled, hence why this was implemented using props.

In short, I see value in both approaches. Documenting the existing selector would immediately unblock people, while exploring a hook or higher-level API could provide a more React-friendly developer experience in the long term.

I’m happy to help move forward with whichever direction we decide is best.

[aprendendofelipe]

I may be overlooking something, but I don't clearly see the advantage of using the withRenderOptions HOC instead of the already viable prop-based approach:

const html = render(<MyTemplate />);
const textHtml = render(<MyTemplate simplified={true} />);
const text = toPlainText(textHtml);

Previously:

const html = render(<MyTemplate />);
const text = render(<MyTemplate simplified={true} />, {
  plainText: true,
});

Regarding useRenderingOptions, its value was clear for avoiding prop drilling, but that utility seems to diminish now that consumers call toPlainText directly.

[aprendendofelipe]

If MyTemplate uses the data-skip-in-text selector, we just need:

const html = render(<MyTemplate />);
const text = toPlainText(html);

[emiliosheinz]

I see now that I overlooked the fact that the plainText option is deprecated in favor of the toPlainText function. Thanks for pointing that out.

Regarding useRenderingOptions, my understanding was that it was introduced to give engineers easier access to the rendering options so they could adapt their templates accordingly. Since most email templates are typically single-level components, I didn’t see prop-drilling as a major concern.

That said, I think both approaches add value, but they seem to address different needs:

• withRenderOptions provides engineers with easy access to rendering options (previously the plainText was an option, so it would also help with hiding elements when rendering the template as text, but that is not true anymore)
• The data-skip-in-text selector focuses on hiding elements when converting from HTML to text.

I'd love to know what maintainers have to say about this :)