Background Images in Email

Background images can transform a plain email into something visually striking — a hero section with text overlaying a photo, a product showcase with a branded pattern behind it, or a footer with a subtle texture. But background images in email come with unique challenges that don't exist on the web, especially around Outlook compatibility and dark mode behavior.

The Email Love Figma Plugin handles the hardest parts for you, including generating the VML code that Outlook requires. This guide covers how to set up background images, what to expect across email clients, and how to avoid common pitfalls.

In the Email Love plugin, the way to add a background image to your email is with the mj-hero-image component. This is a dedicated hero frame designed specifically for background images with content overlaid on top.

You'll find the mj-hero-image component in the Assets tab of the plugin under Heroes, or in the Build Your Own tab. Select it and click to add it to your email.

Step 1: Add the mj-hero-image component to your email from the Assets tab.

Step 2: In Figma's design panel on the right, find the Fill section on the hero image frame. Change the fill type from solid color to Image. Select or upload your background image.

Step 3: Adjust the fill settings. Figma gives you several fill modes — Fill, Fit, Crop, Tile, and Stretch. For email background images, Fill is the most reliable option. It scales the image to cover the entire area.

Step 4: Add your content — headline text, a short line of supporting copy, and a CTA button — inside the hero image frame. These will appear on top of the background image.

The plugin reads the Figma fill and converts it to the appropriate MJML background image properties on export. No manual code editing required.

This is critical to understand before using background images in email:

White text on a background image will turn black in dark mode in email clients like Gmail and Outlook. The email client detects white text and inverts it to black for dark mode readability — but it doesn't know there's a dark background image behind it. The result is black text on a dark image, which is unreadable.

This behavior is outside your control. Email clients apply dark mode transformations automatically, and there's no reliable way to prevent the text color from being overridden.

Our recommendation: Always test your background image sections in dark mode before sending. Use the plugin's preview, Litmus, or Email on Acid to check how your email renders in dark mode across different clients.

Consider using a flat image instead. In many cases, the most reliable approach is to create your hero section as a single flat image (with text baked into the image) rather than using live text over a background image. A flat image won't have its colors inverted by dark mode. The tradeoff is that the text won't be selectable or screen-reader accessible, and the image won't scale as cleanly on mobile — but it will look exactly as designed in every email client and dark mode setting.

Outlook on Windows (2007–2021 and Microsoft 365 desktop) uses the Word rendering engine, which does not support CSS background images. Instead, Outlook requires VML (Vector Markup Language) — a proprietary Microsoft format — to display background images.

The good news: The Email Love plugin generates VML automatically. When you export your email, the plugin wraps your background image with the correct VML code so Outlook renders it properly. You don't need to write or edit VML yourself.

What to keep in mind:

Background images in email require careful attention to file size and dimensions:

Recommended dimensions:

For a standard 640px-wide email, use a background image that is at least 640px wide. For retina/high-DPI displays, use a 1280px wide image. Taller hero sections need proportionally taller images — a 640px × 400px hero should use at least a 640px × 400px image (or 1280px × 800px for retina).

File size matters:

Background images add to your email's total weight. Keep background images under 200KB when possible. Use JPEG for photographic backgrounds and PNG only if you need transparency. Tools like TinyPNG or Squoosh can help compress images without visible quality loss.

Image hosting:

Background images are hosted the same way as regular images. If you have image hosting enabled in the plugin, your background images will be automatically uploaded to the Email Love CDN on export. See the Image Hosting article for details.

If you do use live text over a background image (rather than a flat image), readability is your top priority:

Use high contrast. White text on a dark background image (or dark text on a light background) is essential. If your background image has mixed light and dark areas, consider adding a semi-transparent color overlay in Figma to improve contrast.

Keep it simple. Background image sections work best with minimal content — a headline, a short line of text, and a CTA button. Avoid placing large blocks of paragraph text over background images.

Set a fallback background color. If the background image fails to load (which happens in some email clients, or when images are blocked), the section will show only its background color. Set a solid color that provides enough contrast for your text to remain readable even without the image.

Test in dark mode. As noted above, white text will flip to black in dark mode. Always preview your email in both light and dark mode before sending. If the dark mode rendering is unacceptable, switch to a flat image approach.

Consider mobile. On smaller screens, your background image will scale down, but your text stays the same size relative to the viewport. Test to make sure text doesn't become cramped or overlap awkwardly on mobile devices.

Background image support varies across email clients:

Full support (CSS background-image): Apple Mail (iOS and macOS), Gmail (web, Android, iOS), Yahoo Mail, AOL, Samsung Mail, and most modern email clients support CSS background images natively.

VML support (Outlook on Windows): Outlook 2007–2021 and Microsoft 365 desktop app require VML for background images. The Email Love plugin generates this automatically.

Outlook.com (web): Supports CSS background images. No VML needed.

Dark mode caveats: Gmail (Android, iOS, web) and Outlook (desktop and mobile) will invert text colors in dark mode. This is the most common source of issues with background images in email.

No support: Some older or niche email clients may not render background images at all. In these cases, your background color fallback will display instead.

For a full breakdown, see the Email Client Compatibility Matrix.

Background image not showing in Outlook: Make sure your hero image frame has a Figma image fill (not a nested image layer). The plugin reads the fill property to generate VML. If you placed an image layer behind your content instead of using a fill, the plugin won't recognize it as a background image.

Background image appears cropped: Check that your Figma fill mode is set to Fill rather than Fit or Crop. Also verify that your image dimensions match or exceed the size of your hero image frame.

Background image not loading in the inbox: This usually means the image URL is broken or the image wasn't hosted. Confirm that image hosting is enabled in the plugin settings, or that you've manually uploaded the image to your CDN and the URL is correct.

Text is unreadable in dark mode: This is likely the white-to-black text inversion described above. Your options are: (1) test and accept the dark mode rendering, (2) use dark text on a light background image so the inversion actually helps readability, or (3) convert your hero section to a flat image.

Text is hard to read over the background: Add a solid background color as a fallback. In Figma, you can layer a semi-transparent rectangle over the image to darken or lighten it before placing your text.

Background image looks different on mobile: CSS background images scale based on the container size. On a 375px mobile screen, a background originally designed for 640px will be compressed. Design your background images with important visual elements centered, and test on both desktop and mobile using the plugin's preview or a tool like Litmus.