Adding/customizing WooCommerce email CSS

There’s some surprising gotchas when you want to alter the fonts, colors, and spacing of the WooCommerce order emails. Jump to the option that’s the most appealing to you, and I’ll attempt to save you some headaches:

---

Option 1: changing CSS using a theme file

WooCommerce keeps its default email CSS in a file called email-styles.php. While it’s possible to edit that file directly, it will often be overwritten during WooCommerce updates. Instead, you can set up your own version of this file in your theme:

1. Prepare your theme (ideally a child theme to minimize the risk of changes being overwritten later) by ensuring the wp-content/themes/your-theme-name/woocommerce/emails directory exists, creating it if necessary.
2. Locate wp-content/plugins/woocommerce/templates/emails/email-styles.php and copy it to the directory from the first step.
3. Edit the copy to make any changes you need. Ideally you’ll contain your changes to a block at the end (but before the final <?php tag) for easier updates later. At a minimum, avoid editing anything between the <?php and ?> tags if you’re not familiar with PHP.

While this is the easiest approach, it has one downside: WooCommerce updates frequently change this file for bug fixes and new features. So you may find your emails looking odd in future updates and will need to repeat this process.

Option 2: adding/replacing CSS programmatically

If you’re comfortable with PHP snippets, it’s better to use a hook (whether in your functions.php or a custom plugin) to append your customized CSS to the CSS provided by WooCommerce. This approach preserves your changes when WooCommerce later updates its CSS.

You can do this by adding a filter to woocommerce_email_styles, taking the string it provides, and altering or appending it.

For example, this will add custom CSS after the built-in WooCommerce CSS:

add_filter( 'woocommerce_email_styles', 'mm_add_custom_woocommerce_email_styles', 10, 2 );
function mm_add_custom_woocommerce_email_styles( $css, $email ) {
	return $css . '
.address {
	background-color: gray;
	font-weight: bold; 
}
';
}

You can also use the $email parameter to identify the current email if you’d like custom styles per-email (useful for things like custom formatting for storeowner emails). You do this by comparing the $email->id value with the IDs of the email(s) you’d like to modify (cancelled_order, customer_completed_order, customer_invoice, customer_new_account, customer_note, customer_on_hold_order, customer_processing_order, customer_refunded_order, customer_reset_password, failed_order, or new_order).

Option 3: styling with plugins

I don’t know of any plugins for directly editing the WooCommerce email CSS, but there are plugins for graphically changing style elements. Here are some of the popular options:

• Kadence WooCommerce Email Designer (free, also includes a nice responsive template)
• WooCommerce Email Customizer ($79, developed by WooCommerce)
• Flycart Email Customizer for WooCommerce ($49)
• codemiq WP HTML Mail (WooCommerce support costs €39,00, includes responsive email options)
• cxThemes Email Customizer for WooCommerce ($30, but site is currently down)

What not to do

You’ll find advice online to customize the email CSS by editing the template files (e.g. admin-new-order.php, customer-processing-order.php, customer-completed-order.php, etc.). This may seem like the most straightforward approach, but I’d suggest one of the other options I mentioned: editing those templates is brittle when WooCommerce updates. However, if you decide to use this approach, make sure you:

1. Copy the template files into your theme (ideally a child-theme).
2. Use inline styles (e.g. <p style="font-size: 12pt">) instead of using style blocks/tags. I know this goes against every best-practice for general CSS use, but for email clients it’s the most-compatible approach. It’s what WooCommerce does for you automatically when you change/override email-styles.php.

Why isn’t my CSS working?

If your content looks completely unstyled:

If your email content looks “plain” (no custom colors, fonts, etc.), it’s usually due to problems occurring with the Emogrifier library that WooCommerce uses to inline the CSS for compatibility with the widest range of email clients. The first step to troubleshooting this is to check the WooCommerce logs where Emogrifier errors are written. You may find errors that point to one of two common problems:

1) Emogrifier isn’t loading correctly

Common error messages that suggest this:

• PHP Fatal error: Uncaught Error: Class ‘Emogrifier’ not found
• PHP Fatal error: Uncaught Error: Call to a member function [appendChild, emogrify, etc.] on null

There can be a few reasons for this:

• You’re on a version of PHP lower than 5.5.
• XML isn’t available (how to fix this)
• There’s a version mismatch between your Emogrifier install and either the version being requested, or in the level of CSS support required. This can happen depending on your version of the following, so I’d suggest updating them all (on a staging site) to see if that fixes the issue:
  • WooCommerce itself
  • WooCommerce Email Designer
  • WooCommerce Print Invoices & Packing Lists
  • Other email designing/customizing plugins

2) Emogrifier is loading, but is having trouble parsing the CSS

Common error messages that suggest this:

• PHP Warning: DOMXPath::query(): Invalid expression in /library/woocommerce/includes/libraries/class-emogrifier.php
• PHP Warning: preg_replace(): Compilation failed: invalid range in character class

To troubleshoot this, I suggest temporarily reverting to the email-styles.php provided by WooCommerce and adding your customizations one-by-one until the content goes “plain” again.

If most of the CSS is working, but certain rules/properties are not:

I know of two causes for this:

1. CSS that Emogrifier doesn’t support: check this list to see if your selectors qualify.
2. CSS that the email client doesn’t support: you’d be surprised by the variability in email client support for CSS. Can I email lets you look for compatibility with dedicated clients (Outlook, iOS/Android clients, etc.) and webmail (Gmail, Yahoo, etc.).

You’ve somehow made it to the end of this boring article without falling asleep…

…so here are 3 randomly-generated emojis that will surely tell a compelling story: