Outlook CSS Support: Property by Property, and the Fix

Why Outlook ignores your CSS: the Word rendering engine

Outlook for Windows, from Outlook 2007 to today's Outlook Classic, renders HTML email with the engine that powers Microsoft Word, not a browser engine. This was a deliberate decision in 2007 when Microsoft replaced the Internet Explorer rendering engine with Word's. It has never been reversed.

Word was built for printable office documents, not for the CSS the web has written since. When it meets a property it does not know, such as border-radius or a function such as linear-gradient(), it drops it. No error, no fallback, no warning. The email just looks broken, and you only find out if you test in Outlook Classic itself: a browser preview draws the CSS Word throws away.

Outlook on the web, on a Mac and the new Outlook for Windows render with browser engines and support much more. The client to plan for is Outlook Classic on Windows: 51 of 300 features work in Outlook Classic · 26 partial · 222 not supported · 1 untested.

Which Outlook uses which rendering engine

The name "Outlook" covers five clients with different engines. An email that looks right in Outlook.com can be broken in Outlook 2019 on Windows.

The full matrix for the desktop app is in the Outlook Classic compatibility reference.

Outlook Classic CSS support, property by property

Each row says what Outlook Classic does with the property and links to its support page. The note under it is the short version of the fix; the linked guide has the code.

• Not supporteddisplay:flex is not supported in Outlook Classic.Use tables. For columns that sit side by side, see Outlook ghost tables.
• Not supporteddisplay:grid is not supported in Outlook Classic.Same as flexbox: lay the columns out with a table.
• Partialmax-width is partly supported in Outlook Classic.Give Outlook a fixed-width table inside conditional comments; the ghost table guide has the pattern.
• Not supportedborder-radius is not supported in Outlook Classic.Draw the shape with VML or accept square corners: border-radius in Outlook.
• Not supportedlinear-gradient is not supported in Outlook Classic.Declare a solid background-color first: gradients in Outlook.
• Not supportedobject-fit is not supported in Outlook Classic.Crop the image to size before sending: object-fit in Outlook.
• Not supportedbackground-image is not supported in Outlook Classic.Use a VML <v:rect> with a solid background colour behind it; the VML background image guide has the full wrapper.
• Not supportedbox-shadow is not supported in Outlook Classic.Drop it for Outlook Classic, or fake a hard shadow with a darker border on a wrapping table cell.
• Not supportedborder-spacing is not supported in Outlook Classic.Use the cellspacing attribute on the table instead.
• Not supportedbox-sizing is not supported in Outlook Classic.Set widths with the width attribute on table cells and put padding on an inner cell, so the total stays the width you set.
• Partial<style> is partly supported in Outlook Classic.Inline the styles your layout depends on; some other clients, Gmail's apps reading non-Google accounts among them, drop the block.
• Partialmargin is partly supported in Outlook Classic.Centre with align="center" on the containing table, not with margin on inner elements.
• Not supported@font-face is not supported in Outlook Classic.A stack with fonts Outlook doesn't know ahead of Arial renders in Times New Roman. Set Arial in an MSO-only style: <!--[if mso]><style>* { font-family: Arial, sans-serif !important; }</style><![endif]-->.

Outlook Classic is rarely the only client that drops these. The support across all 21 clients is on the pages for linear-gradient, box-shadow, border-spacing and box-sizing.

Word also reads its own CSS: mso- properties such as mso-line-height-rule, and markup inside <!--[if mso]> comments that no other client sees. Both are covered in MSO conditional comments and mso- CSS.

If you already scoped Gmail-only CSS with u + .body, a matrix that still blames Outlook is wrong; see email client targeting CSS.

Replacing flexbox with tables in MJML and React Email

The most common mistake is laying the email out with flexbox. Both frameworks have components that compile to tables, so use those instead:

<!-- This breaks in Outlook -->
<mj-section>
  <mj-column>
    <mj-text css-class="hero">Welcome!</mj-text>
  </mj-column>
</mj-section>

<mj-style>
  .hero { display: flex; align-items: center; }
</mj-style>

<!-- Do this instead, MJML compiles to tables automatically -->
<mj-section>
  <mj-column vertical-align="middle">
    <mj-text>Welcome!</mj-text>
  </mj-column>
</mj-section>

// This breaks in Outlook
<div style={{ display: 'flex', gap: '16px' }}>
  <img src="logo.png" />
  <p>Welcome to our app</p>
</div>

// Do this instead
import { Row, Column, Img, Text } from '@react-email/components';

<Row>
  <Column>
    <Img src="logo.png" width="48" height="48" />
  </Column>
  <Column>
    <Text>Welcome to our app</Text>
  </Column>
</Row>