Meta viewport

The meta viewport was originally invented by Apple for the iPhone. Since web developers started to use it a lot, other mobile browsers also implemented it, including the parts that don’t make sense.

Meanwhile W3C has reverse-engineered a specification. Although I’d love to study it more and compare it to my findings, I’m afraid it’s so densely written that I do not understand it — even now that I understand the meta viewport itself. For instance, I think that W3C’s extend-to-zoom concept is the same as my ideal viewport, but I’m not totally sure. So I hope that this page will serve as an English translation of the specification, but I’m not sure it is.

My notes for this research. Not necessarily comprehensible to anyone else.

This page contains my tests for the various directives in the meta viewport tag.

The @viewport construct is not part of this research. I’ll phase it in later when I know how it should behave.

The meta viewport tag

The meta viewport tag contains instructions to the browser in the matter of viewports and zooming. In particular, it allows web developers to set the width of the layout viewport relative to which CSS declarations such as width: 20% are calculated.

The meta viewport has the following syntax:

<meta name="viewport" content="name=value,name=value">

Directives

Every name/value pair is a directive. (The word is my own invention.) There are six of them in total:

width. Sets the width of the layout viewport.

initial-scale. Sets the initial zoom of the page AND the width of the layout viewport.

minimum-scale. Sets the minimum zoom level (i.e. how much the user can zoom out).

maximum-scale. Sets the maximum zoom level (i.e. how much the user can zoom in).

height. Is supposed to set the height of the layout viewport. It is not supported anywhere.

user-scalable. When set to no prevents the user from zooming. This is an abomination that MUST NOT be used.

device-width value

There is one special value: device-width for the width directive. It sets the layout viewport width to the ideal viewport width.

In theory there’s a similar device-height value, but it doesn’t seem to work EXCEPT.

The three viewports

Ages ago I reported that mobile browsers have two viewports: the visual one and the layout one. Re-read this article if necessary; I assume knowledge of these two viewports in what is to follow.

The ideal viewport

See the devices page for some ideal viewport examples of the browsers on my devices.

It turns out that there’s a third viewport, which I decided to call the ideal viewport. It gives the ideal size of a web page on the device. Thus, the dimensions of the ideal viewport differ per device.

On old or cheap devices with non-retina screens the ideal viewport is equal to the physical number of pixels, but that’s not a requirement. Newer devices with higher physical pixel densities may well retain the old ideal viewport, because it’s ideally suited to the device.

Up to and including the 4S, the iPhone ideal viewport is 320x480, regardless of whether it has a retine screen or not. That’s because 320x480 is the ideal size for web pages on these iPhones.

There are two important things about the ideal viewport:

The layout viewport can be set to ideal viewport values. The width=device-width and initial-scale=1 directives do so.

Allscale directives are relative to the ideal viewport, and not to whatever width the layout viewport has. So maximum-scale=3 means the maximum zoom is 300% of the ideal viewport.

Finding the ideal viewport dimensions

It might occasionally be useful to be able to read out the ideal viewport dimensions. Tough luck.

Well, you can do it. Give a page the following meta tag and read out document.documentElement.clientWidth/Height:

<meta name="viewport" content="width=device-width,initial-scale=1">

If that’s not an option you have no way of reading out the ideal viewport dimensions. I hoped screen.width/height might be helpful here, but only BlackBerry gives the correct information. The other browsers resort to various shades of unhelpfulness.

Open question: shouldscreen.width/height give the ideal viewport dimensions?
Pro: the properties would at last contain useful information.
Con: ideal viewport size does not necessarily equate physical pixels on the device.

Compatibility - ideal viewport

Here is all of the above in easy table format.

Test

iPhone

iPad

Android Samsung

Android HTC

Chrome

Opera Presto

BlackBerry

IE

ideal viewport size

320 x 480

768 x 1024

400 x 640

360 x 640

601 x 962

240 x 320

342 x 570

320 x 480

There is no right or wrong here. The values depend on the device, and all values are reasonable.

Layout viewport width

Before rendering the page, the browser needs to know how wide the layout viewport is. This is the viewport relative to which CSS declarations such as width: 20% are calculated.

Without any further instructions the browsers pick a width themselves. In six of the eight tested browsers this is 980px, in BlackBerry and IE10 it’s 1024px. There’s no right or wrong here; this is just the browser vendors making a choice.

When you use width=400 or another numerical value in the meta viewport tag, the layout viewport’s width is set to that value. We already knew that.

However, Android WebKit’s and IE’s minimal viewport is 320px. When you go below 320px they revert to the ideal viewport width.

Then there’s the case when the layout viewport becomes equal to the ideal viewport. This happens when you do width=device-width or initial-scale=1. It’s complicated, since there are bugs in Safari and IE10 and there’s a catch to using initial-scale, but this is the general rule.

Minimum and maximum dimensions

The maximum width of the layout viewport is 10,000 pixels. I don’t entirely trust that number, since the browsers do not allow you to zoom out to this amount. Still, for now I accept this official value.

The minimum width of the layout viewport is about 1/10th of the ideal viewport, which is also the maximum zoom level. (I.e. the layout viewport never becomes smaller than the smallest possible visual viewport.) Exceptions: Android WebKit and IE, which never go below 320px.

Zoom

Zoom is tricky. In theory it sounds simple: determine the zoom factors that the user can zoom in or out to. The problem is two-fold:

We cannot directly read out the zoom factor. Instead, we have to read out the width of the visual viewport, which has an inverse relation to the zoom factor. The larger the zoom factor, the smaller the visual viewport width.
So the minimum zoom factor determines the maximum visual viewport width, and vice versa.

It turns out that all zoom factors are relative to the ideal viewport, no matter what the current size of the layout viewport is.

Then there is the matter of the name. In Apple-speak, zoom is scale, and the meta viewport directives are thus called initial-scale, minimum-scale, and maximum-scale. The other browsers were forced to comply in order to retain compatibility with iPhone-specific websites.

The three directives expect a zoom factor, where for instance 2 means “zoom to 200% of the ideal viewport width.”

Formulas

Thus, with a ideal viewport width of 320px and a zoom factor of 2 we get a visual viewport width of 160px. The width of the layout viewport plays no part in this calculation.

Minimum and maximum zoom factors

I did some extra tests on the Huawei C8813, Android 4.1.1, because it has a landscape ideal viewport width of 569.

Here, too, the minimum and maximum zoom factors were 0.25 and 4. So these powers of 4 are actually a general Android WebKit rule, and not just an artifact of the specific 640px width of the Samsung and HTC test phones.

The maximum visual viewport width here is 2277px, which is about 4 x 569.

What are the minimum and maximum zoom factors the browsers support?

First, a restriction. The visual viewport can never become wider than the layout viewport, so in most practical cases the minimum zoom factor is ideal viewport width / layout viewport width.

Still, in these tests I can use absurd layout viewport widths such as 5,000. I did so, and the results are:

Android WebKit’s minimum zoom factor is 0.25 and its maximum 4. This cannot be changed. HOWEVER, it uses 640 / 0.25 = 2,560px, which is correct for landscape, even in portrait mode.

IE’s maximum visual viewport width is 1024px. Its maximum zoom factor is 6 in portrait and 6 and 2/3 in landscape. This cannot be changed.

In the other browsers, without any zoom directives, the minimum zoom factor is about 0.25 and the maximum about 5.

Adding directives such as a huge layout viewport width or a huge maximum-scale causes the minimum factor to go to about 0.1 and the maximum to about 10.

There are slight differences in these factors; see the table below.

So in theory the iPhone’s visual viewport width can be anything between 32px (zoom factor 10) and 3200px (zoom factor 0.1).

Android WebKit has a maximum visual viewport width of 2560px, which is 4x640 (landscape). It also uses this value for portrait mode.

IE has a maximum visual viewport width of 1024px
because that’s the maximum width of the layout viewport.

initial-scale

Setting he initial-scale directive actually does two things:

It sets the initial zoom factor of the page to the defined value, calculated relative to the ideal viewport. Thus it generates a visual viewport width.

It sets the layout viewport width to the visual viewport width it just calculated.

So let’s say we have an iPhone in portrait mode and give it an initial-scale=2 without any further instructions. By now, it shouldn’t surprise you that this sets the visual viewport width to 160px (= 320 / 2). That’s how the scaling directives work.

However, it also sets the width of the layout viewport to 160px. So we now have an 160px wide page in minimum zoom. (The visual viewport cannot become larger than the layout viewport, so zooming out is not possible.)

And no, this doesn’t make the slightest bit of sense. If asked for my candid opinion I’d probably mumble something like “completely fucking batshit insane.” Still, there’s no doubt that browsers behave like this.

Browser bugs

Except for Android WebKit. Obviously. Android WebKit allows initial-scale to set the layout viewport width only if the value is 1 AND there is no width directive. So only initial-scale=1 without any other directives works.

As to IE, it applies the wrong ideal viewport (320x320 instead of 320x480), and also pretends any value is 1. So the value you give to the initial-scale doesn’t matter in IE.

Conflicting width directives

Since initial-scale sets the layout viewport width, you can now create conflicting directives:

<meta name="viewport" content="initial-scale=1,width=400">

What happens now? The browser gets conflicting orders. Let’s return to the iPhone 4S once more:

initial-scale=1 tells it to set the layout viewport width to 320px portrait and 480px landscape.

width=400 tells it to set the layout viewport width to 400px in both portrait and landscape.

The browser solves the problem by obeying the largest width in portrait or landscape. In our example the portrait layout viewport width becomes 400px (the larger of 320 and 400), and the landscape layout viewport width 480px (the larger of 480 and 400).

Makes sense? Actually it doesn’t, but browsers do it anyway.

In any case, what we have here is a min-width for the layout viewport. The meta tag above sets the min-width to 400px, but allows the browser to grow the layout viewport beyond that if device size and orientation require it.

I’m not sure if there’s any practical use for a min-width for the layout viewport, but if you need one, hey, it’s there!

Browser bugs

Android WebKit does not follow these rules. If the width equals device-width or is smaller than 320, Android WebKit always applies the ideal viewport width to the layout viewport. Above 320 it always obeys the width directive.

IE does not follow these rules above width=480, when it sets the layout viewport width to 1024px.

Rule: the browser compares the width directive and the outcome of the initial-scale directive, and applies the highest resulting width to the layout viewport. This is done independently for portrait and landscape.

Rule: the browser compares the width directive and the outcome of the initial-scale directive, and applies the highest resulting width to the layout viewport. This is done independently for portrait and landscape.

Rule: the browser compares the width directive and the outcome of the initial-scale directive, and applies the highest resulting width to the layout viewport. This is done independently for portrait and landscape.

Minor iPhone bug

If a combination of width and initial-scale causes the browser to automatically zoom in in landscape mode (i.e. visual viewport is smaller than layout viewport)

AND the user zooms out in landscape mode and then switches to portrait mode

the minimum-scale for portrait equals the minimum-scale for landscape (i.e. the viewport width) times the portrait/landscape ratio. (So a landscape viewport width of 400 causes a portrait minimum-scale of 268.)

Solution: zoom in as much as possible in portrait. The bug disappears.

Try it here. Hold your iPhone in landscape, go to the page, and follow the instructions above.

minimum- and maximum-scale

I did only one small series of tests for minimum-scale and maximum-scale. They generally seem to work quite well, except on Android WebKit, which doesn’t support minimum-scale, and IE, which makes a horrific mess of things — so badly, in fact, that I’ve given up trying to understand what’s going on.

What’s supposed to happen in the tests below is that the layout viewport width is calculated as described above, and after that zooming is restricted to between 50% and 200%, i.e. the visual viewport can become from twice as large to twice as small as the ideal viewport.

One exception: the visual viewport can never become smaller than the layout viewport.