First, Understand Your Screen

I unashamedly maintain that there is so much more to being successful on the mobile web than dealing with screen size. But I do accept that dealing with screen size is at least a first step.

Thank goodness then, that the matter of screen size is so simple and well understood.

Really?

As web developers, we will often need to know the screen size of the device we are displaying content on. Perhaps on the server, perhaps on the client, perhaps to be used as a clause in a media query.

But how best to measure it? And what are we measuring anyway? On the client-side, for instance, a variety of ways exist to determine screen and page size: things like screen.width , window.outerWidth , document.body.clientWidth , and so on. But these properties are infamously unspecified by any standards: so what do they all mean – and how reliable are they on mobile browsers?

Required reading at this point is PPK’s viewport article. With an article of tables from him that long, you know something’s up.

But last week I pushed out an update to src.sencha.io which allows client-side screen size parameters. Which parameters should mobile developers use? And when?

So for this blog post, I looked at a range of these metrics, and recorded their values for a variety of mobile browsers and page conditions. I’ve been working in mobile for far too long, but still, the amount of diversity in the results shocked me. Read on for the gory details, or skip to the end for the TLDR. I think there are some interesting findings.

Methodology

The tests comprised a very simple web page, containing several paragraphs of meaningless Latin, and a JavaScript function that runs to take screen measurements within the browser. The following properties are sought:

screen.width

screen.availWidth

window.outerWidth

window.innerWidth

document.body.clientWidth

document.body.offsetWidth

@media device-width

@media width

screen.height

screen.availHeight

window.outerHeight

window.innerHeight

document.body.clientHeight

document.body.offsetHeight

@media device-height

@media height

window.orientation

@media orientation

The CSS media query properties ( device-width , orientation , etc) are taken programmatically by evaluating expressions with the matchMedia() function, supported in iOS v5.0 and Android v4.0.

I’m sorry to say that the tests were run on emulators rather than real devices, but covered iPhone (iOS v5.0 and iOS v4.3), Android v2.3, Android v4.0, and Opera Mobile v11.0. The Android and Opera simulators were set to use HVGA (320×480) so as to have conditions as consistent with the iPhone as possible. (Even though the actual physical screen of a retina iPhone is 640×960, this HVGA resolution is the one reported to the software APIs).

The tests were run with two different HTML document types – HTML5 and XHTML-MP – and also a third time with no doctype specified. The tests were also run both with and without a viewport meta tag to control the default width (constrained to ‘ device-width ‘) and scaling. Additionally each device was tested with landscape as well as portrait orientation – making a total of 12 test combinations for each browser.

For the iPhone and Android browsers, PhoneGap-wrapped versions of the test pages were also run (without the viewport meta tag), and finally, for iOS v5.0, the iPhone’s ‘Add to Homescreen’ technique was used (with the apple-mobile-web-app-capable meta tag) to launch portrait versions of the tests in a full-screen mode.

As if all those combinations were not enough, the properties were accessed four times during the lifecycle of the page: a) inline before the <body> tag, b) after the </body> tag, c) on the document’s load event, and d) one more time, 250ms later. I had a hunch that the values – at least those relating to page height – might change throughout this lifecycle.

Results

The full set of results is available here. The various combinations of conditions are across the top, and operating systems (and measurements made) are down the left. Each cell shows the value returned from the relevant API call, and ‘ - ‘ is used where the call failed or returned an undefined value.

Where the value changed during the lifecycle of the page, slashes delimit the change, and a letter is used to indicate at which of the four measuring points the value changed. So for example, ‘ 208/c:1962 ‘ means that a value was 208 before the <body> and after the </body> , but then it changed to 1962 for ‘c’, the document’s load event, and remained so 250ms later.

There’s a lot to digest in there, although you may at least have noticed – as I have – that homogeneity is scarce. You may notice some particularly strange results, particularly on Android, but also on iOS and Opera. Let’s analyze the data by slicing the findings by property measured, dicing by operating system, and trying to digest the whole sorry lot.

Analysis

<a target='table' href="/assets/2011/12/table.html?r=screen.width&c=">screen.width</a> & <a target='table' href="/assets/2011/12/table.html?r=screen.height&c=">.height</a>

These two properties are generally understood to return the physical dimensions of the screen upon which a browser is running. On desktop browsers, they will return you 1024×768, 1440×900, 1600×1200 and so on, regardless of how the actual browser window is sized. On mobile devices, one would expect the same behavior, and get full physical screen sizes.

Well, close. But no cigar.

Opera Mobile and Android v4.0 (as well as v2.3 in a PhoneGap app) behave most intuitively in this regard, and will indeed report 320×480 or 480×320 for portrait and landscape respectively.

iOS also consistently reports the physical dimensions of the screen (320×480), but notably fails to flip them for a change or orientation. So be aware that in landscape mode, your browser’s width will actually, apparently, be reported to be larger than the screen’s.

Android v2.3, in a regular browser scenario, however, displays even more curious behavior. Its screen.width always starts off as 800 – which is clearly some sort of virtual viewport, rather than the physical screen. But when the document has an XHTML-MP doctype, or a constrained viewport (for any doctype), the value will switch, by the time of the document load event, to be the 320 or 480 you might expect.

Now this might be tolerable if you remember to wait for documents to fully load before accessing this property, but even that caution is blown to the wind by Android v2.3’s screen.height behavior.

With a non-constrained viewport, a portrait orientation, and with no doctype, screen.height was reported during this test as 1003. With an HTML5 doctype, it also switched to 1003, but only after dallying at 498 until at some point after the document load event. With an XHTML-MP doctype, it also started out at 498, but then dropped to about 40% of that value (199) by the time of the document load. With a constrained viewport, behavior was stable as a function of doctype, but also demonstrated the 60% drop at document load: from 1003 down to 401.

Landscape-wise, the same sort of issues occur: with no doctype, screen.height is a reliable 402; and with an HTML5 doctype, the same value is also (eventually) returned. The XHTML-MP doctype, or a constrained viewport, will cause the eventual value to be 241, but by way of various intriguing values. Our constrained, HTML5 document, for example, reported 372 before and after the <body/> , 223 on load, and 241 at some point afterwards.

Yes, these actual values are probably dependent upon the length of my particular test page itself, but remember that these are supposed to be the physical screen dimensions, folks!

Some semblance of normality returns to Android v2.3 in the PhoneGap environment. The values of 455 and 295 are hardly accurate measures of physical screen size, either (since bizarrely they seem to take the 25 pixel status bar into account!), but at least they’re close, and hooray: take solace that the value does not change during the page lifecycle.

<a target='table' href="/assets/2011/12/table.html?r=availWidth&c=">screen.availWidth</a> & <a target='table' href="/assets/2011/12/table.html?r=availHeight&c=">.availHeight</a>

In the desktop world, the available width and height returned by these two properties still relate to the whole screen, rather than the browser’s window, but they take operating system chrome into account. The menu bar in OSX means that screen.availHeight is at least 26 pixels less than screen.height , for example – although the width values will probably be the same (unless you have a non-minimizing dock on the side of the screen).

In mobile, one might expect the available values to take into account any OS status bar height. Let’s see, shall we?

I need to caveat the Opera results here, since the simulator runs in a dedicated window without any ‘real device’ chrome. But that should have implied that its available dimensions are the same as the screen’s – and this was not what was seen. In fact, the availHeight is reduced to 369 from a height of 480, not by any OS chrome, but by the browser’s own rather fat chrome. This is not what is expected – even if, on a real device, it emerges that the OS chrome is deducted too.

And having labored over Android v2.3, above, there’s not much more to say here about that operating system either. Without exception it depressingly reports exactly the same values for <a target='table' href="/assets/2011/12/table.html?r=android23screen.availwidth&c=">availWidth</a> and <a target='table' href="/assets/2011/12/table.html?r=android23screen.availheight&c=">availHeight</a> as it did for width and height – although at least that means that the PhoneGap values are now correct! Android v4.0’s browser also reports the same available values as it did for total <a target='table' href="/assets/2011/12/table.html?r=android40screen.availwidth&c=">width</a> and <a target='table' href="/assets/2011/12/table.html?r=android40screen.availheight&c=">height</a> , but fortunately they were slightly more sensible to begin with. But bizarrely the PhoneGap app doesn’t take the status bar height off as it does for v2.3.

And then there’s iOS: it does successfully deduct 20 pixels for the operating system’s chrome. But remember that orientation is ignored! So although a portrait availHeight is sensibly 460 (having dropped from 480), it is anti-intuitively the width in a landscape orientation that is reduced (from 320 to 300) by a bar at the top of the screen!

Quirks on all fronts. Sigh.

<a target='table' href="/assets/2011/12/table.html?r=outerwidth&c=">window.outerWidth</a> & <a target='table' href="/assets/2011/12/table.html?r=innerwidth&c=">.innerWidth</a>

In contrast to the screen properties, the window properties are understood to refer to the browser window itself. For desktop browsers, (at least, when they’re not running in full-screen mode), the outer dimensions will normally be smaller than those for the screen. The inner dimensions then further deduct browser chrome: window borders, toolbars, status bars, and so on, and so they are normally smaller still.

In mobile, we might expect the outer values to more or less match those for the available screen – since apps run full size. And indeed, with <a target='table' href="/assets/2011/12/table.html?r=outerwidth&c=">window.outerWidth</a> , we have a good news story.

iOS v5.0 uses <a target='table' href="/assets/2011/12/table.html?r=ios50window.outerw&c=">window.outerWidth</a> to redeem itself over the lack of the orientation’s effect on screen. It is 320 for portrait viewing, and 480 for landscape viewing. Bam.

Opera does the same. Bam. Astonishingly, Android v2.3 also nails it. Bam.

In fact, the only small blot that stops window.outerWidth being the model student is Android v4.0 in landscape: the property often has the portrait value of 320 before the <body> tag is reached. However, this is arguably an edge case, and a very minor misdemeanor.

After that rousing news, it’s back to earth with a small bump for window.innerWidth . If your desktop experience had convinced you that innerWidth must be the same or smaller than outerWidth , you’ve now got the TARDIS-like experience of mobile viewports to enjoy.

Without dropping into classic viewport theory here, it’s sufficient to say that WebKit mobile browsers seem to use the boundary between the window’s ‘inner’ and ‘outer’ width and height properties to delineate the world of physical pixels and the world of viewport pixels: the latter a realm where zooming, pinching and tapping allow the mobile browser to sensibly scale web pages designed for much larger screens.

For those pages where the viewport’s behavior is constrained, perhaps through the use of meta tags, this is of little concern, since the mapping of the two worlds is 1:1. And indeed, in our tests, when such a tag is present, <a target='table' href="/assets/2011/12/table.html?r=window.innerw&c=">innerWidth</a> takes exactly the same value as <a target='table' href="/assets/2011/12/table.html?r=window.outerw&c=">outerWidth</a> – modulo the Android race conditions, at least.

Less well-known might be the fact that, for all these browsers, when an XHTML-MP doctype is present, the same is also true. We’ve alluded to this already: the presence of this forces the viewport width to be the same as the physical width of the screen (either 320 or 480), while still allowing subsequent scaling.

And of course, PhoneGap’s default configuration is also to constrain the viewport, so the values there also match.

But when the viewport has not been constrained, and an HTML5 doctype (or none at all) is used, innerWidth will suddenly start to represent values much larger than the physical screen: and represent the width of the viewport canvas upon which the page has been rendered.

On a portrait iPhone, for example, the default viewport is 980 pixels. On a landscape iPhone it is, well, according to window.innerWidth , 981 (yes, really).

Android 2.3 and earlier used a different value of 800 for the default viewport width, and this is exposed as <a target='table' href="/assets/2011/12/table.html?r=android23window.innerw&c=800">window.innerWidth</a> (as well as the vestigal value before document load for the constrained tests). With Android 4.0, the default viewport has been brought in line with the iPhone’s: 980 pixels.

<a target='table' href="/assets/2011/12/table.html?r=outerh&c=">window.outerHeight</a> & <a target='table' href="/assets/2011/12/table.html?r=innerh&c=">.innerHeight</a>

Mobile browsers normally have no vertical chrome, so apart from the matter of viewports, outerWidth and innerWidth values corresponded relatively nicely. However, they do have horizontal chrome elements: address bars at top, and toolbars at bottom. So we should expect the height to be reduced accordingly.

Opera, in a way, gets this right. We have already pointed out it surprisingly deducted the browser chrome to calculate its screen.availHeight . But since it then promptly uses the same value for <a target='table' href="/assets/2011/12/table.html?r=opera11window.outerh&c=">window.outerHeight</a> and <a target='table' href="/assets/2011/12/table.html?r=opera11window.innerh&c=">window.innerHeight</a> , it meets our expectations on the latter of these two properties at least.

For Android, <a target='table' href="/assets/2011/12/table.html?r=android40window.outerh&c=">window.outerHeight</a> is also relatively deterministic. Again, there are timing wobbles, but after page load, the values are consistently 455 (in portrait) and 295 (in landscape). The Android OS bar, as we’ve mentioned, is 25 pixels.

But it’s iOS that baffles this time. Only in homescreen mode, with an HTML5 doctype (or none at all), does the browser report the expected window.outerHeight value of 460.

In all other cases, bizarre numbers come out. For iOS v5.0, for constrained portrait pages, it’s 356 that becomes 445. For non-constrained portrait pages it’s 356 that becomes 1602. For constrained landscape pages it’s 208 that becomes 667. For non-constrained portrait pages it’s 208 that becomes 1702. In PhoneGap, it’s 460 that becomes 1602, or 480 that becomes 1202. And for constrained homescreen apps, it’s 480 that becomes 1602.

The fact that this is the one property whose values significantly vary from iOS v4.3 to iOS v5.0 also raises alarm bells.

Perhaps we could write a whole blog post to reverse engineer is going on here. 356 and 208 seem to have some plausibility, but apart from that – who knows? There’s no apparent Safari documentation for this property, and even WebCore’s own test suite describes the expected results as ‘empirical‘.

I think I can safely caution you never to use window.outerHeight in iOS and expect a meaningful answer.

After that, window.innerHeight seems relatively stable and predictable. In constrained (and XHTML-MP) scenarios in the regular iOS browser, it sits at that familiar 356 value for portrait and 208 for landscape. This is the actual inner height of the browser window, sans browser chrome, as per documentation. (The fact that these two values are not the same amount less than the physical screen dimensions is due to the fact that the landscape toolbar is slightly shallower than the portrait one.)

This pattern is also consistent when the page is launched constrained from the homescreen or in a PhoneGap application. Here, without any browser chrome at all, the values correctly return to the physical screen dimensions minus the 20 pixel tool bar.

However, this value is not as trustworthy when the page has a non-constrained viewport and an HTML5 (or omitted) doctype. In our test, window.innerHeight had values of 1091 and 425 for the two orientations – doubtless dependent upon the length of the content in our actual page – and hard to predict. As if to prove that point, in homescreen mode, this value increases to 1409. Not particularly useful.

When we look at window.innerHeight for Android, the results appear to follow a similar pattern, but, as usual, are somewhat obfuscated by the fact they change throughout the page lifecycle. For constrained viewports, the two orientations’ values are 401 and 241 in Android v2.3 (where the address bar is 54 pixels high), and 403 and 243 in Android v4.0 (where the address bar is 52 pixels high), and the PhoneGap values are also as expected, considering there is no address bar.

But again, the determinism disappears when the viewport is not constrained, the reported values as varied 1234, 496, 1003 and 402. We can deduce that these are viewport lengths rather than window size, that they are content-dependent, and that they change between platform versions due to the updated viewport width – but again, their utility is more doubtful than in the constrained scenarios.

<a target='table' href="/assets/2011/12/table.html?r=offsetw&c=">body.offsetWidth</a> , <a target='table' href="/assets/2011/12/table.html?r=clientw&c=">.clientWidth</a> , <a target='table' href="/assets/2011/12/table.html?r=offseth&c=">.offsetHeight</a> , & <a target='table' href="/assets/2011/12/table.html?r=clienth&c=">.clientHeight</a>

We move onto our final set of JavaScript APIs, and we might hope that we are leaving the vagaries of BOM implementations and entering the consistency of the DOM & CSSOM (although, sadly, these properties are still not under the purview of any W3C standard).

These four values should theoretically be available on all DOM elements: the ‘offset’ dimensions include an element’s content, padding and border, while the ‘client’ dimensions are the content and padding alone. Neither include the margin, as detailed in Mozilla’s documentation.

In our case, we are querying these properties for the document’s body, and, since it has no border, the offset and client values should be the same. Our test pages add a CSS margin of 10 pixels, so on the desktop, we would expect its width, at least, to be 20 pixels less than window.innerWidth . Empirically, desktop browsers seem to use the two heights to represent the total length of the page, rather than the height of the window display. (I’d thought that would be body.scrollHeight , but that’s another story.)

How do mobile browsers fare? How does the viewport concept affect these values?

With offsetWidth and clientWidth , iOS and Android work broadly as you would expect. The non-constrained viewports return measurements in the high 900s (and around 800s for Android v2.3), and the constrained pages in the low 300s (for portrait) and mid 400s (for landscape).

It’s notable how and when the choice of doctype affects these values though. With an HTML5 doctype, non-constrained viewport tests on both platforms report 20 pixels less than the viewport size for both values: 960 pixels regardless of orientation.

With an XHTML-MP doctype, as we’ve previously mentioned, the viewport becomes the device width by default, and again 20 pixels are correctly deducted to give us values of 300 and 460 in landscape and portrait respectively. The same expected behaviour is seen with HTML5 doctypes used on constrained viewports.

What is slightly strange is when no doctype is used. In this case, again on both platforms in all scenarios, the clientWidth is the full viewport width (980, 800, 480 or 320), and the offsetWidth is reduced by the margin (to 460, 780, 460, or 300). This seems systemic: as though the lack of doctype puts the browser into a mode where it interprets the body’s margin as a border.

Across all of our testing combinations, though, the offsetHeight and clientHeight values are the most bizarre set of results in the whole experiment.

There are three patterns on Android and iOS. Firstly, pages with no doctype will always have clientHeight equal to window.innerHeight once the </body> tag has closed – but the offsetHeight will be completely different. Secondly, when there is a doctype, the <a target='table' href="/assets/2011/12/table.html?r=clienth&c=html">clientHeight</a> and <a target='table' href="/assets/2011/12/table.html?r=offseth&c=html">offsetHeight</a> are always the same, and nearly always regardless of what the doctype actually is. (The bizarre exception is Android v2.3 where the HTML5 doctype on the non-constrained viewport causes both values to reduce dramatically at some point after the document load event). And finally, the offsetHeight value of the non-doctype test always produces the same values as the clientHeight and offsetHeight of the HTML5 equivalent.

Got that?

But what the values actually are seems extremely non-deterministic. We’ve already commented on the arbitrary nature of window.innerHeight which the non-doctype results seem to echo. But despite the doctype, orientation and viewport size, the meaning of these values would seem very hard to assess. The best we can say is that when clientWidth or offsetWidth go up, clientHeight or offsetHeight go down (as seems sensible), but that no attention seems to be paid to our 20 pixel margin.

Again, properties best left alone, I think.

In contrast to iOS and Android, which use window outer and inner dimensions as the point of delineation between physical pixels and the viewport, Opera Mobile’s strategy seems to have been to to stay in the world of real pixels until this last <a target='table' href="/assets/2011/12/table.html?r=opera11doc&c=">document.body</a> set of measurements, and finally we get a sense of how it sizes the viewport.

The default viewport width seems to be 850 pixels, but although Opera has, until now, remained oblivious to the pages’ doctypes, the values seem to suddenly be very dependent upon them. With an HTML5 doctype on a non-constrained viewport, both clientWidth and offsetWidth are 830 (which probably has had the 20 pixel margin deducted), and with XHTMLMP, we get 300 or 460 (which would be consistent with a constrained viewport, also minus margins).

But with no doctype and no viewport constraint, in either portrait or landscape, we get 850 for clientWidth (i.e. no padding) and… for offsetWidth , 2048! What?

And finally, as they were for iOS and Android, the clientHeight and offsetHeight are a fairly disparate bunch of values. The only assumptions we can make are that a) constrained clientHeight with no doctype will be the same as window.innerHeight after the </body> tag; that b) clientHeight and offsetHeight for constrained HTML and any type of XHTML-MP will all be the same value for a given orientation (and that non-constrained HTML5 will also eventually converge on that value sometime after the document load event); and c) that the values themselves will be more or less unpredictable.

But perhaps not as meaningless as the offsetHeight for non-constrained doctype-less pages. It’s consistent. But a highly unlikely 40960 – which must surely, more or less, mean undefined !

@media <a target='table' href="/assets/2011/12/table.html?r=@mediadevice-w&c=">device-width</a> & <a target='table' href="/assets/2011/12/table.html?r=@mediaw&c=">width</a> , <a target='table' href="/assets/2011/12/table.html?r=@mediadevice-h&c=">device-height</a> & <a target='table' href="/assets/2011/12/table.html?r=@mediah&c=">height</a>

We conclude the menagerie of screen dimensions by looking at the values used in CSS3 media queries. These are used as ‘features’ in declarations which are used to conditionally load stylesheets or apply the rules within them. Media queries are a staple of contemporary web design, and perhaps should be understood by designers as much as the other properties above need to be understood by developers handling layouts.

Finally, we have some properties which are defined by a standard.

Because, for this test, we needed to evaluate these values in JavaScript, we use the matchMedia function and varied the operand until it returned true. This does mean we only have results for those devices which support that API call: namely iOS v5.0 and Android v4.0.

Well it’s nice to end with some good news. In both platforms, in all conditions, @media device-width always returns the same value as screen.width , and device-height always returns the same value as screen.height . There’s no matchMedia support in Opera, but I’ll assume the same would be true.

This is great – but of course don’t forget the main issue afflicting those measurements: the lack of rotated values in iOS and Android 2.3’s wacky 800 viewport value which I’ll postulate may be echoed here too.

@media width and height also track other JavaScript properties in both platforms. @media width is almost always equal to window.innerWidth (except in non-constrained landscape mode in iOS v5 when the former is 980 and the former that curious 981). @media height is always equal to window.innerHeight .

(It’s not so clear whether this pattern would be followed by Opera too, were we able to measure it this way. To confirm, it would require a CSS-based test harness – perhaps another study.)

But there are a couple of things worth saying about this observation. Firstly, the window.innerWidth and window.innerHeight values themselves are something of a bit of a mixed bag. See the earlier discussions above.

Secondly, it’s interesting to note that the matchMedia result changes with page lifecycle in the same way that the regular JavaScript measures do. This may mean that media queries change their results as the page loads – I don’t know how to predict when these parametric CSS rules are evaluated – and I imagine this might create conditions under which certain resources referred to in the CSS, loaded early in the page (when the size is evaluated to one thing), might turn out to have been unneccessary later in the page’s life (when the size is evaluated to quite another thing).

Hardcore browser theory & probably more testing required.

<a target='table' href="/assets/2011/12/table.html?r=.orien&c=">window.orientation</a> & @media <a target='table' href="/assets/2011/12/table.html?r=aorien&c=">orientation</a>

As a final aside, note that we also measured orientation results. window.orientation returns the number of degrees (0 for portait, 90 for landscape), and is flawless in iOS, and set correctly after </body> on Android. (Just remember not to evaluate orientation before the <body> – it’s likely still to be 0 in landscape mode)

Opera does not seem to support the API.

The media query equivalent is also apparently fine (where measurable). The only Android timing quirk here is PhoneGap in portrait which thinks it’s landscape at first. I guess nothing’s perfect.

Summary

Wow. Painful, on the whole.

Let’s see what we can briefly conclude. I’m not going to go back through each of the properties, but a couple of things jumped out at me.