When an outlined CSS headline renders as flat text in iOS Safari, the cause is almost always one of five things: the outline depends on paint-order: stroke fill over -webkit-text-stroke and WebKit paints that combination differently from Chrome, a text-shadow has no explicit color, the stroke width is in units that collapse on a small screen, a font fallback on iOS changes the glyph outlines, or the page was only ever checked in headless Chromium. The fix that holds up everywhere is to turn the stroke off (-webkit-text-stroke: 0; paint-order: normal;) and draw the outline with eight colored text-shadow offsets plus one drop shadow, then verify in the iOS Simulator or on a real iPhone, not in a headless browser.
Three properties are involved. -webkit-text-stroke is a WebKit extension, now written into the WHATWG Compatibility Standard, that draws a stroke of a given width and color at the edge of each glyph. paint-order is an SVG property that also applies to HTML text and decides whether the fill or the stroke is painted first; the default, normal, paints fill, then stroke, so half of a thick stroke eats into the letter. text-shadow paints one or more offset copies of the text behind it. The popular "outside stroke" recipe sets paint-order: stroke fill so the fill covers the inner half of the stroke, then adds a shadow for depth.
Why does text stroke work in Chrome but not iOS Safari?
Desktop Chrome and iOS Safari use different rendering engines, and the stroke, paint order and shadow code paths for HTML text are not shared between them. Every browser on iOS uses WebKit, so Chrome on an iPhone behaves like Safari, not like Chrome on a laptop. A headline that looks right in Chrome on a Mac proves nothing about how it paints on a phone.
We ran into this on one of our own concept sites. An outlined display headline used -webkit-text-stroke, paint-order: stroke fill and a text-shadow. It looked correct in desktop Chrome and in every automated screenshot. In iOS Safari, checked in the iOS Simulator, it rendered with no outline and no shadow: flat text. Our screenshot pipeline ran on headless Chromium, which supports paint-order on HTML text, so the automated checks hid the bug completely.
We could not find a WebKit bug report that describes exactly this result, so treat it as what we observed, not as a documented rule. What is documented is that the combination is fragile across engines: the 2025 Interop proposal for better stroked text (web-platform-tests/interop issue 759) laid out cross browser differences in stroke corners and in how text-shadow relates to the stroke, and it was not selected for Interop 2025.
The five causes we find most often.
- Stroke plus paint order on HTML text: the outline depends on
paint-order: stroke fillover-webkit-text-stroke, a pairing each engine paints its own way, and on iOS we have seen it render with no stroke at all - Shadow with no color:
text-shadow: 4px 4px 0leaves the color to the browser, and MDN's compatibility data notes that in Safari shadows without an explicit color are transparent - Hairline stroke units: a stroke set in
emorvwcan compute below one device pixel at phone widths and effectively vanish - Font fallback on iOS: the webfont fails or is still loading, iOS falls back to a system face, and the stroke and shadow sit on glyphs you never designed for
- Headless only QA: the page was approved from Chromium screenshots, which never exercised WebKit's text painter
Does iOS Safari support paint-order on HTML text?
Yes, on paper: MDN's browser compatibility data lists paint-order on stroked HTML text from Safari 11 and iOS Safari 11, and from Chrome 123. Before those versions both engines supported the property only partially, and it did not affect stroked HTML text. WebKit's change landed in February 2017 (WebKit bug 168601, which added paint-order, stroke-linecap and stroke-linejoin to text rendering for video captions). MDN marks paint-order Baseline widely available, with March 2024 as the date it became available across browsers.
As of October 2026 that is still the documented state. Supported does not mean identical. The property is supported; the way stroke, fill and shadow combine on a given font at a given size is not specified tightly enough to look the same in every engine. That gap is where our flat headline came from.
How do you verify what iOS Safari actually renders?
Only WebKit on iOS tells you what iOS shows, so check in the iOS Simulator or on a real iPhone before you sign off. Three tools, in this order.
The iOS Simulator. With Xcode installed, boot a device and open the page from the terminal with xcrun simctl openurl booted https://your-preview-url, then capture it with xcrun simctl io booted screenshot headline.png. Look at the screenshot at full size. A flat headline is obvious once you look.
Safari Web Inspector against the Simulator. In desktop Safari, turn on Settings, Advanced, Show features for web developers. The Develop menu then lists the booted Simulator; pick the page and inspect the headline. Check the computed values for -webkit-text-stroke-width, paint-order and text-shadow, and confirm the webfont actually loaded in the Network tab.
A real iPhone. Connect it, enable Web Inspector under Settings, Safari, Advanced on the phone, and it shows up in the same Develop menu. Use it for the final pass, because the Simulator renders with the Mac's GPU. Treat this check like any other launch gate on a preview, the same way we treat broken images on password protected previews.
Diagnose top to bottom.
This is the order we run. Each step isolates one layer, so you stop at the first real failure.
text-shadow. If the stroke appears, the shadow and stroke are interacting. If nothing changes, the stroke itself is not painting.paint-order to normal. If the stroke appears (thinner, centered on the glyph edge), the paint order combination is your cause.-webkit-text-stroke-width. If it resolves below 1px at phone width, set a pixel floor with max(2px, 0.04em) or switch to the shadow outline.font-display before judging the outline.text-shadow layer with an explicit color, such as 4px 4px 0 #111. A colorless shadow is the cheapest cause to rule out.What is the reliable fix for an outlined headline?
Turn the stroke off and draw the outline with eight colored text-shadow offsets plus one drop shadow; every major engine has painted multiple text shadows for years. MDN's compatibility data has multiple shadows in Safari since 4 and iOS Safari since 3. This is what we shipped:
.headline { color: #fff; -webkit-text-stroke: 0; paint-order: normal; text-shadow: -3px -3px 0 #111, 0 -3px 0 #111, 3px -3px 0 #111, -3px 0 0 #111, 3px 0 0 #111, -3px 3px 0 #111, 0 3px 0 #111, 3px 3px 0 #111, 8px 8px 0 rgba(0, 0, 0, 0.35); }
The eight shadows cover the four sides and four corners, which reads as a solid outline at display sizes. Use about 2px to 3px for headlines on phones. The last layer is the offset drop shadow. Two limits: the corners get slightly rounded rather than sharp, and very thick outlines start to look lumpy, so keep the offset modest. If you need a true vector outline at large sizes, an inline SVG <text> with stroke and paint-order: stroke is the other route, since SVG text has used paint-order in Safari since version 8.
| Symptom | Likely cause | Fix |
|---|---|---|
| Flat text on iPhone, outlined in desktop Chrome | Stroke plus <code>paint-order: stroke fill</code> painted differently by WebKit | Stroke off, eight shadow outline |
| Outline fine, drop shadow missing in Safari | Shadow written without a color | Add an explicit color to every shadow layer |
| Outline thin or gone only on phones | Stroke width in em or vw computes under 1px | Pixel floor with <code>max()</code> or shadow outline |
| Outline eats into the letters | Default <code>paint-order: normal</code> centers the stroke on the edge | Shadow outline, or SVG text with paint-order |
| Outline wraps a different typeface | Webfont failed, iOS fell back to a system font | Fix the font URL, check it loads with a 200 |
| Screenshots pass, phones fail | QA ran on headless Chromium only | Add an iOS Simulator screenshot to the checklist |
| Same flat text in Chrome on iPhone | All iOS browsers use WebKit | Test in any iOS browser, fix once |
What is normal and what is a red flag?
Small differences in stroke corners and shadow edges between Chrome, Firefox and Safari are normal; a headline that loses its outline entirely on one engine is a red flag. The Interop proposal documented that engines draw stroke corners differently (rounded in one engine, miter like breaks in another) and that text-shadow is cast from the text and not from the stroked result. Expect a pixel or two of difference at the corners.
Red flags: the outline is gone, the shadow is gone, the text is a different face, or the headline wraps to a different number of lines on iPhone. Any of those means the design is not shipping as approved. We put an iOS Simulator screenshot of the hero on the pre launch list next to redirects and indexing, the same list we use in our website migration checklist, because the hero is the first thing a visitor on a phone sees.
Why do automated screenshots miss this bug?
Headless Chromium supports paint-order on HTML text from Chrome 123, so a Chromium based screenshot shows the stroke exactly as designed. The bug lives in a different engine. Playwright can launch a WebKit build, which is closer, but it is not Safari on iOS and should not be your final check. The same lesson applies to anything that depends on the device: a page can pass every automated check and still fail for real visitors, which is why we also check things like analytics scripts breaking form submissions and a security checkpoint blocking the site on a real device before calling a launch done.
Why is -webkit-text-stroke not working on iPhone?
Check four things: the computed stroke width is at least 1px at phone width, the webfont loaded, the stroke is not paired with paint-order: stroke fill and a text-shadow, and you are testing in WebKit. On one of our sites that combination rendered flat in iOS Safari. Replacing the stroke with eight colored text-shadow offsets fixed it.
Does Safari support paint-order on HTML text?
MDN's compatibility data lists it from Safari 11 and iOS Safari 11. Earlier versions supported paint-order only for SVG. Support means the property is recognized; the result can still differ from Chrome when stroke, fill and shadow are combined.
How do I make an outside text stroke that works in every browser?
Set -webkit-text-stroke to 0 and draw the outline with eight text-shadow layers, one for each side and corner, all with an explicit color, then add any drop shadow as the last layer. For a true vector outline at large sizes, use inline SVG text with stroke and paint-order.
Why does my text-shadow not show in Safari?
Give the shadow an explicit color. MDN's compatibility notes say Safari treats shadows without an explicit color as transparent. Also check that a stroke and paint-order combination is not suppressing the whole text effect.
Is Chrome on iPhone different from Safari for CSS rendering?
No. Browsers on iOS use WebKit, so Chrome, Firefox and Safari on an iPhone paint text the same way. If the outline is missing in one, it is missing in all of them.
How do I test iOS Safari without an iPhone?
Install Xcode, boot an iOS Simulator, open the page with xcrun simctl openurl booted and your URL, and capture it with xcrun simctl io booted screenshot. Inspect it from desktop Safari's Develop menu. Do a final pass on a real device when you can.