Developing websites for Apple Watch [Updated]

Caution! This article was published over a year ago, and hasn't been updated since. Situation, software and support of the topic below could have changed in the meantime.

Apple's WWDC 2018 keynote was rather boring - at least if you are not a fan of the snapchatification of each and every messenger app.

But roughly in the middle of the keynote, right between Apple Watch's life-saving capabilities and a very American multi-tasking demonstration (#mommyforthewin) there was a rather interesting bit for web developers:

"With watchOS 5, we've integrated WebKit, so now you have the ability to view web content in mail or messages." – Kevin Lynch, WWDC 2018 Keynote

Web developers on twitter instantly squealed: "So one more media query"?

Some hours after the event, Apple/WebKit published an 8-minute video on "Designing web content for watch OS" and it is packed with valuable info. Here's what the video says (I haven't tested it yet):


  • Of course, scrolling works as you expect it to work: By dragging your finger on the display or using the Digital Crown
  • Double tapping zooms into the page, which is also familiar from WebKit in iOS
  • Force touch on the watch, or "a firm press" as the video calls it, opens an action menu, consisting of:
    • Forward and backward buttons
    • Toggle for reader mode
    • Refresh button
  • But when it comes to navigating in your history, swiping left and right over the edges also works


Compared with WebKit's capabilities on iOS and mac OS the following restrictions apply:

  • No video playback
  • No Web fonts
  • No ServiceWorkers

Legacy layout on Apple Watch WebKit

WebKit on watch OS 5 works with the "(min-width: 320px)" media query since it communicates dimensions of 320x357 pixels, although the real device dimensions in actual pixels differ. Apple claims that "320px based layouts" will zoom out, content will get smaller, but the overall layout is preserved.

To make this work, WebKit on watch OS 5 overrides initial scale from 1.0 to 0.59.

Optimizing layout for Apple Watch WebKit

Developers can also communicate to WebKit that this page is already optimized for Apple Watch, disable the "default adaptations" by using the following meta tag:

<meta name="disabled-adaptations" content="watch">

"This allows WebKit to treat the view port's device width as the real width of Apple watch." – Wenson Hsieh, WWDC 2018 Workshop

Form elements

When dealing with form elements, Apple advises to:

  • Choosing the most appropriate type attribute for your element, e.g. tel, date, and password. This, of course, is reasonable advice not only when dealing with smartwatches but also smartphones, any device with no classic keyboard and web semantics in general.
  • Label your elements (you are already doing it for accessibility and usability reasons, right?). Since using an input on Apple Watch WebKit is a "full screen matter", Apple advices you to give context by labelling form elements, either by labels themselves, the aria-label attribute or placeholders. Please beware: The mention of the placeholder attribute as context indicator is bad advice in my opinion. So Watch WebKits behaviour and communication is a two-edged sword here regarding accessibility: On the one hand visually representing the value of aria-label (that's a first, right?), on the other hand teaching that it is okay to use placeholders a label substitute (see the WebAxe article "Placeholder Attribute Is Not A Label!").

Reader Mode

The last part of the video deals with serving web pages to Watch WebKit's reader mode, which works the same as its siblings on iOS and mac OS do.


So, not another media query - but a new meta tag if you're feeling lucky. What I like is that "optimizing websites for Apple Watch" means - summarized - working with best practices. I reckon Apple Watch, and smartwatches in general, won't ever gain the same amount of traction as smartphones did to change web development considerably. But still - acknowledging I haven't yet tested it - fitting your web pages into a watch could have been a much more proprietary process.

[Update June 07, 2018]

Wenson Hsieh of WebKit (who narrated and, I guess, created the WWDC 18 workshop video) reached out to me via twitter, explaining their intention regarding form labels:

"[Placeholders are] no substitute for labeling form controls. However, it is a valuable source of context for a focused element, in the absence of any other attributes/labels! It's preferable to have a real <label> associated with the form control, or at least specify an aria-label — currently, the order of precedence that determines what text goes in the status bar if there are multiple potential sources is (1) text of an associated label, (2) arial-label attribute, (3) title attribute, and finally (4) placeholder as a last resort."