Need help with your emails? Contact us at hello@mailingui.com
Docs
Getting Started
Theming

Theming

MailingUI is a set of opinionated React components, built on top of React.email (opens in a new tab), designed to make the creation of emails easier. Before you continue, make sure to read Getting Started - Introduction.

Theming MailingUI components is powered by our theme config (fancy way of calling our theme object). Although this object could end up being completely different to the starting point we offer, it will give you typesafety and give you the sense of utility classes and merged styles in your components using inline CSS (which is ultimately the safest way to style Email).

You have two options to update theming:

Modifying the theme config

Scenario: We want to create a Lead component. So we will introduce a new color and a new variant to use in our MailingUI components.

Adding Colors

Add any color in three easy steps:

/themes/theme.ts
// 1. ADD A COLOR VARIANT (i.e., "hotpink")
// This is how your color will be referenced as
type ColorVariants = "global" | "hotpink";
 
// 2. DECLARE ITS CSS COLOR VALUE
// Completely type-safe and with autocompletion
const colors: ThemeColors = {
  global: "#262626",
  hotpink: "hotpink"
};
 
// 3. USE YOUR NEW COLOR
// Completely type-safe and with autocompletion
export const theme: Theme = {
  global: {
    fontFamily: "system-ui, sans-serif",
    color: colors.hotpink,
  },
  {...}
};

Creating a style

Add any style in three easy steps:

/themes/theme.ts
// 1. ADD A THEME VARIANT (i.e., "lead")
// This is how your style will be referenced as
type ThemeVariants =
  | "global"
  | "headings"
  | "lead"
 
// 2. DECLARE ITS CSS STYLE
// Completely type-safe and with autocompletion
export const theme: Theme = {
  global: {
    fontFamily: "system-ui, sans-serif",
    color: colors.hotpink,
  },
  lead: {
    fontSize: remToPx(1.5),
    fontStyle: "italic",
    fontWeight: 500,
  },
  {...}
};
/components/Lead.tsx
// 3. USE YOUR NEW STYLE
// Completely type-safe and with autocompletion
import * as React from "react";
import { cx } from "@mailingui/utils";
 
export const Lead: React.FC<React.ComponentPropsWithoutRef<"p">> = ({
  style,
  ...props
}) => <p style={cx(["global", "lead", style])} {...props} />;

Using cx to apply styles

Taking an obvious inspiration, we've created an cx utility function to apply styles. It's code is simple but yet effective at its job. This is how we use it:

/components/Lead.tsx
import * as React from "react";
import { cx } from "@mailingui/utils";
 
export const Lead: React.FC<
  React.ComponentPropsWithoutRef<"p"> & { small?: boolean }
> = ({ small, style, ...props }) => (
  // You can add theme variant keys and CSS properties, both conditionally
  <p
    style={cx(["global", "lead", small && { fontSize: "14px" }, style])}
    {...props}
  />
);

Using applyTheme utility for file-based theming

When applying a theme, you have to provide the theme property on each individual usage of a themable component. This utility allows you to apply theme at the top of your files and use the components already with a theme included in your JSX syntax eliminating the need to specify it every time.

/components/Header.tsx
import * as React from "react";
import { Column, Row } from "@react-email/components";
 
import * as components from "@mailingui/components";
import { applyTheme } from "emails/utils/applyTheme";
 
import { theme } from "../theme";
 
const { Img } = applyTheme(components, theme);
 
export const Header: React.FC = () => {
  return (
    <Row>
      <Column>
        <Img
          compact
          width={119}
          height={29}
          src="/logo.png"
          alt="Company Logo"
        />
      </Column>
    </Row>
  );
};

Using MDX and context themes

If you are using MDX and will need to update theme on an email-basis. You have the option to enable your components with a theme prop and pass it in your cx function. You do not need this if you plan to manage your themes exclusively with the theme config.

/components/Lead.tsx
import * as React from "react";
import { Theme } from "@mailingui/themes";
import { cx } from "@mailingui/utils";
 
export const Lead: React.FC<
  React.ComponentPropsWithoutRef<"p"> & { small?: boolean; theme?: Theme }
> = ({ small, theme, style, ...props }) => (
  // Add your theme using a prop and `cx`
  <p
    style={cx(["global", "lead", small && { fontSize: "14px" }, style], {
      theme,
    })}
    {...props}
  />
);

Then use the Markdown component to pass custom theme styles:

import * as React from "react";
 
import { Body, Container, Html, Head, Row, Column } from "@react-email/components";
 
import Example from "./CustomStyles.mdx";
import { Markdown, Lead } from "@mailingui/components";
 
export default function Email() {
  return (
    <Html>
      <Head />
      <Body>
        <Container>
          <Row>
            <Column>
              <Markdown
                theme={{
                  lead: {
                    fontFamily:
                      "'Iowan Old Style', 'Palatino Linotype', 'URW Palladio L', P052, serif",
                  },
                }}
              >
                <Example title="Latest News" />
              </Markdown>
            </Column>
          </Row>
        </Container>
      </Body>
    </Html>
  );
}

Congratulations! 🥳 You're set for theming. Go ahead and make email feel a bit more modern and less 2010.

Manual InstallUsage