CSS Viewport

Editor's Draft 13 October 2010

This version:

http://people.opera.com/rune/TR/ED-css-viewport-20101013/

Latest version:

http://people.opera.com/rune/TR/css-viewport/

Previous version:

http://people.opera.com/rune/TR/css-viewport/ED-css-viewport-20100806/

Editors:

Rune Lillesveen (Opera Software)

Copyright © 2010 Opera Software

Abstract

This specification provides a way for an author to specify, in CSS, the size and the zoom factor of the viewport that is used as the base for the initial containing block.

Status of this document

Table of contents

• 1. Introduction
• 2. Values
• 3. The viewport
• 4. The @-o-viewport rule
  • 4.1. Syntax
• 5. Viewport properties
  • 5.1. The ‘min-width’ and ‘max-width’ properties
  • 5.2. The ‘width’ shorthand property
  • 5.3. The ‘min-height’ and ‘max-height’ properties
  • 5.4. The ‘height’ shorthand property
  • 5.5. The ‘zoom’ property
  • 5.6. The ‘min-zoom’ property
  • 5.7. The ‘max-zoom’ property
  • 5.8. The ‘user-zoom’ property
  • 5.9. The ‘orientation’ property
• 6. Constraining viewport property values
  • 6.1. Definitions
  • 6.2. The procedure
• 7. Media Queries
• 8. Conformance
• 9. Viewport META element
  • 9.1. Properties
  • 9.2. Parsing algorithm
  • 9.3. Translation into @-o-viewport properties
• 10. References
  • Normative references
  • Other references
• Property index

1. Introduction

This section is not normative.

CSS 2.1 [CSS21] specifies an initial containing block for continuous media that has the dimensions of the viewport. Mobile/handheld device browsers have a viewport that is generally a lot narrower than a desktop browser window at a zoom level that gives a CSS pixel size recommended by CSS 2.1.

The narrow viewport is a problem for documents designed to look good in desktop browsers. The result is that mobile browser vendors use a fixed initial containing block size that is different from the viewport size, and close to that of a typical desktop browser window. In addition to scrolling or panning, zooming is often used to change between an overview of the document and zoom in on particular areas of the document to read and interact with.

Certain DOCTYPEs (for instance XHTML Mobile Profile) are used to recognize mobile documents which are assumed to be designed for handheld devices, hence using the viewport size as the initial containing block size.

Additionally, an HTML META tag has been introduced for allowing an author to specify the size of the initial containing block, and the initial zoom factor directly. It was first implemented by Apple for the Safari/iPhone browser, but has since been implemented for the Opera, Android, and Fennec browsers. These implementations are not fully interoperable and this specification is an attempt at standardizing the functionality provided by the viewport META tag in CSS.

2. Values

This specification follows the CSS property definition conventions from [CSS21].

Value types are defined in section 4.3 of [CSS21].

3. The viewport

This specification introduces a way of overriding the size of the viewport provided by the user agent (UA). Because of this, we need to introduce the difference between the initial and actual viewport.

Initial viewport

This refers to the viewport before any UA or author styles have overridden the viewport given by the window or viewing area of the UA. Note that the initial viewport size will change with the size of the window or viewing area.

Actual viewport

This is the viewport you get after the cascaded viewport properties, and the following constraining procedure have been applied. Note that the actual viewport may differ from the initial viewport even when there are no author specified viewport properties because of the default viewport width.

Default viewport width

A UA may choose to use a default width that is different from the initial viewport width for reasons described in the Introduction. If it is different from the initial viewport width, it is recommended that it is the desktop-width. The alternative would be to have "@-o-viewport { width: desktop-width; }" as part of the UA stylesheet for the UAs that use a desktop width for the default viewport. The problem with that is user/author stylesheets which do not override width, but specify some of the other properties. "@-o-viewport { initial-scale: 1; }" as part of the user/author style would then still give you "desktop-width". We could say that the existence of any user or author styles for @-o-viewport would reset min/max-width to auto.

When the actual viewport cannot fit inside the window or viewing area, either because the actual viewport is larger than the initial viewport or the zoom factor causes only parts of the actual viewport to be visible, the UA should offer a scrolling or panning mechanism.

It is recommended that initially the upper-left corners of the actual viewport and the window or viewing area are aligned if the base direction of the document is ltr. Similarly, that the upper-right corners are aligned when the base direction is rtl. The base direction for a document is defined as the computed value of the direction property for the first BODY element of an HTML or XHTML document. For other document types, it is the computed direction for the root element.

4. The @-o-viewport rule

The @-o-viewport at-rule consists of the @-keyword followed by a block of property declarations describing the viewport.

The property declarations inside an @-o-viewport rule are per document properties and there is no inheritance involved. Hence declarations using the ‘inherit’ keyword will be dropped. They work similar to @page properties and follow the cascading order of CSS. Hence, properties in @-o-viewport rules will override properties from preceding rules. The declarations allow !important which will affect cascading of properties accordingly.

@-o-viewport {
  width: device-width;
}

4.1. Syntax

The syntax for the @-o-viewport rule is as follows (using the notation from the Grammar appendix of CSS 2.1 [CSS21]):

viewport
  : VIEWPORT_SYM S*
    '{' S* declaration? [ ';' S* declaration? ]* '}' S*;

with the new token:

@-{O}-{V}{I}{E}{W}{P}{O}{R}{T} {return VIEWPORT_SYM;}

where:

V               v|\\0{0,4}(56|76)(\r\n|[ \t\r\n\f])?|\\v
W               w|\\0{0,4}(57|77)(\r\n|[ \t\r\n\f])?|\\w

The viewport non-terminal is added to the stylesheet production along with the ruleset, media, and page non-terminals:

stylesheet
  : [ CHARSET_SYM STRING ';' ]?
    [S|CDO|CDC]* [ import [ CDO S* | CDC S* ]* ]*
    [ [ ruleset | media | page | viewport ] [ CDO S* | CDC S* ]* ]*
  ;

It is also added to media production to allow @-o-viewport rules nested inside @media rules This is extending the CSS 2.1 syntax. A draft of CSS3 Paged Media also allows page inside @media.:

media
  : MEDIA_SYM S* media_list LBRACE S* [ ruleset | viewport ]* '}' S*
  ;

5. Viewport properties

This chapter presents the properties that are allowed inside an @-o-viewport rule. Other properties than those listed here will be dropped.

Relative length values are resolved against initial values. For instance 'em's are resolved against the initial value of the font-size property.

5.1. The ‘min-width’ and ‘max-width’ properties

Specifies the minimum and maximum width of the viewport that is used to set the size of the initial containing block where

<viewport-length> = auto | device-width | device-height | desktop-width | <length> | <percentage>

and the values have the following meanings:

‘auto’

The used value is calculated from the other property values according to the procedure in Chapter 6.

‘device-width’

The width of the screen in CSS pixels at zoom factor 1.0.

‘device-height’

The height of the screen in CSS pixels at zoom factor 1.0.

‘desktop-width’

UA specific width that is used as the initial containing block width when showing documents designed for a desktop UA.

For desktop browsers, this will typically be the same as the window width. For mobile browsers, typically a fixed value of 850px, 980px, or some other value found suitable.

<length>

A non-negative absolute or relative length.

<percentage>

A percentage value relative to the width or height of the initial viewport at zoom factor 1.0, for horizontal and vertical lengths respectively. Must be non-negative.

The min-width and max-width properties are inputs to the constraining procedure in Chapter 6. The width will initially be set as close as possible to the initial viewport width within the min/max constraints. See Chapter 6 for further details.

5.2. The ‘width’ shorthand property

This is a shorthand property for setting both min-width and max-width. One <viewport-length> value will set both min-width and max-width to that value. Two <viewport-length> values will set min-width to the first and max-width to the second.

5.3. The ‘min-height’ and ‘max-height’ properties

Specifies the minimum and maximum height of the viewport that is used to set the size of the initial containing block.

The min-height and max-height properties are inputs to the constraining procedure in Chapter 6. The height will initially be set as close as possible to the initial viewport height within the min/max constraints. See Chapter 6 for further details.

5.4. The ‘height’ shorthand property

This is a shorthand property for setting both min-height and max-height. One <viewport-length> value will set both min-height and max-height to that value. Two <viewport-length> values will set min-height to the first and max-height to the second.

5.5. The ‘zoom’ property

Specifies the initial zoom factor for the window or viewing area.

Values have the following meanings:

‘auto’

The used value is calculated from the other property values according to the procedure in Chapter 6.

<number>

A non-negative number used as a zoom factor. A factor of 1.0 means that no zooming is done. Values larger than 1.0 gives a zoomed-in effect and values smaller than 1.0 a zoomed-out effect.

<percentage>

A non-negative percentage value used as a zoom factor. A factor of 100% means that no zooming is done. Values larger than 100% gives a zoomed-in effect and values smaller than 100% a zoomed-out effect.

5.6. The ‘min-zoom’ property

Specifies the smallest allowed zoom factor. It is used as input to the constraining procedure, but also to limit the allowed zoom factor that can be set through user interaction.

Values have the following meanings:

‘auto’

The used value is calculated from the other property values according to the procedure in Chapter 6.

<number>

A non-negative number limiting the minimum value of the zoom factor.

<percentage>

A non-negative percentage limiting the minimum value of the zoom factor.

5.7. The ‘max-zoom’ property

Specifies the largest allowed zoom factor. It is used as input to the constraining procedure, but also to limit the allowed zoom factor that can be set through user interaction.

Values have the following meanings:

‘auto’

The used value is calculated from the other property values according to the procedure in Chapter 6.

<number>

A non-negative number limiting the maximum value of the zoom factor.

<percentage>

A non-negative percentage limiting the maximum value of the zoom factor.

5.8. The ‘user-zoom’ property

Specifies if the zoom factor can be changed by user interaction or not.

Values have the following meanings:

‘zoom’

The user can interactively change the zoom factor.

‘fixed’

The user cannot interactively change the zoom factor.

5.9. The ‘orientation ’ property

This property is used to request that a document is displayed in portrait or landscape mode. For a UA/device where the orientation is changed upon tilting the device, an author can use this property to inhibit the orientation change.

Values have the following meanings:

‘auto’

The UA automatically chooses the orientation based on the device's normal mode of operation. The UA may choose to change the orientation of the presentation when the device is tilted.

‘portrait’

The document should be locked to portrait presentation.

‘landscape’

The document should be locked to landscape presentation.

6. Constraining viewport property values

6.1. Definitions

For the procedure below:

Computed values refer to the computed values from the property definitions. Other values refer to the values resolved/constrained to at that point in the procedure. The values are initially resolved to their computed values.

width and height refer to the resolved viewport size and not the shorthand properties. They are both initially ‘auto’.

MIN/MAX computations where one of the arguments is ‘auto’ resolve to the other argument. For instance, MIN(0.25, 'auto') = 0.25, and MAX(5, 'auto') = 5.

initial-width is the width of the initial viewport in pixels at zoom factor 1.0. On a device this is typically (device-width - decorations). On Safari/iPhone this is identical to the device-width.

initial-height is the height of the initial viewport in pixels at zoom factor 1.0. Typically (device-height - decorations).

default-width is the default viewport width, in pixels, as defined in Chapter 3.

6.2. The procedure

The used values are resolved from the computed values going through the steps below. The procedure is closely modelled after the behavior of the Safari/iPhone browser. We have run tests on the Android SDK browser and a Fennec nightly build for Windows to see where the various implementations are the same and where they differ. We found that the Safari implementation is by far the most consistent and predictable, and decided to ignore the other implementations for this specification. This procedure, and the parsing algorithm, are backed up by a compliance test suite currently consisting of 120-130 tests. All but one pass in the tested Safari browser.

User agents are expected, but not required, to re-run this procedure and re-layout the document, if necessary, in response to changes in the user environment, for example if the device is tilted from landscape to portrait mode or the window that forms the initial viewport is resized.

Resolve non-‘auto’ width and height to pixel values

1. Resolve relative and absolute lengths, percentages, and keywords (‘device-width’, ‘device-height’, ‘desktop-width’) to pixel values for the ‘min-width’, ‘max-width’, ‘min-height’ and ‘max-height’ properties

Resolve initial width and height from min/max properties

2. If min-width or max-width is not ‘auto’, set width = MAX(min-width, MIN(max-width, initial-width))
3. If min-height or max-height is not ‘auto’, set height = MAX(min-height, MIN(max-height, initial-height))

Clamp values to range

4. If width is not ‘auto’, set width = MIN(10000, MAX(width, 1))
5. If height is not ‘auto’, set height = MIN(10000, MAX(height, 1))
6. If zoom is not ‘auto’, set zoom = MIN(10, MAX(zoom, 0.1))
7. If min-zoom is not ‘auto’, set min-zoom = MIN(10, MAX(min-zoom, 0.1))
8. If max-zoom is not ‘auto’, set max-zoom = MIN(10, MAX(max-zoom, 0.1))

Resolve min-zoom and max-zoom values

9. If min-zoom is ‘auto’, set min-zoom = 0.25
10. If max-zoom is ‘auto’, set max-zoom = 5, and min-zoom = MIN(5, min-zoom)
11. Set max-zoom = MAX(min-zoom, max-zoom)

Resolve zoom value

12. If the computed value of ‘zoom’ is ‘auto’ and width is not ‘auto’, set zoom = (initial-width / width)
13. If zoom is ‘auto’, set zoom = (initial-width / default-width)
14. If the computed value of ‘zoom’ is ‘auto’ and height is not ‘auto’, set zoom = MAX(zoom, (initial-height / height))

Constrain zoom value to min-zoom/max-zoom range

15. Set zoom = MIN(max-zoom, MAX(min-zoom, zoom))

Resolve width value

16. If width and the computed value of ‘zoom’ are both ‘auto’, set width = default-width
17. If width is ‘auto’, and height is ‘auto’, set width = (initial-width / zoom)
18. If width is ‘auto’, set width = height * (initial-width / initial-height)

Resolve height value

19. If height is ‘auto’, set height = width * (initial-height / initial-width)

Extend width and height to fill the window/viewing area for the resolved zoom

20. Set width = MAX(width, (initial-width / zoom))
21. Set height = MAX(height, (initial-height / zoom))

@-o-viewport {
  width: device-width;
  zoom: 0.5;
}

7. Media Queries

For several media features, the size of the initial containing block and the orientation of the device affects the result of a media query evaluation, which means that the effect of @-o-viewport rules on media queries needs extra attention.

From the Media Queries specification [MEDIAQ]:

“To avoid circular dependencies, it is never necessary to apply the style sheet in order to evaluate expressions. For example, the aspect ratio of a printed document may be influenced by a style sheet, but expressions involving ‘device-aspect-ratio’ will be based on the default aspect ratio of the user agent.”

Recommended procedure for applying CSS rules:

1. Apply @-o-viewport rules. If @-o-viewport rules rely on media queries, use the viewport properties of the initial viewport, but with width set to the default viewport width.
2. Apply style rules. If style rules rely on media queries, use the viewport properties obtained from step 1 when evaluating the media queries.

The rationale for using the viewport properties obtained from applying the @-o-viewport rules for evaluating media queries for style rules, is that media queries should match the actual viewport that the document will be layed out in and not the initial or default one. Consider the example below given that the UA has a default viewport width of 980px, but a device-width and initial viewport width of 320px. The author has made separate styles to make the document look good for initial containing block widths above or below 400px. The actual viewport used will be 320px wide, and in order to match the styles with the actual viewport width, the viewport resulting from applying the @-o-viewport rules should be used to evaluate the media queries.

@-o-viewport {
  width: device-width;
}

@media screen and (min-width: 400px) {
  div { color: red; }
}

@media screen and (max-width: 400px) {
  div { color: green; }
}

Another example:

@media screen and (width: 397px) {
  div { color: green; }
}

@-o-viewport {
  width: 397px;
}

Below is an example where an @-o-viewport rule relies on a media query affected by the viewport properties.

@-o-viewport {
  width: 397px;
}

@media screen and (width: 397px) {
  @-o-viewport {
    width: 500px;
  }
}

@media screen and (width: 397px) {
  div { color: green; }
}

It is recommended that authors do not write @-o-viewport rules that rely on media queries whose evaluation is affected by viewport properties. Is is also recommended that the @-o-viewport rule(s) is placed as early in the document as possible to avoid unnecessary re-evaluation of media queries or reflows.

Next example illustrates possible circular dependencies between media queries and @-o-viewport rules. Assuming a default viewport width larger than 200px, the first viewport rule would apply causing an actual viewport width of 100px. If the media queries were based on the actual viewport, a re-evaluation would apply the second @-o-viewport rule which would in turn cause the first media query to be true, which means we're back to start.

@media screen and (min-width: 200px) {
  @-o-viewport {
    width: 100px;
  }
}

@media screen and (max-width: 200px) {
  @-o-viewport {
    width: 300px;
  }
}

8. Conformance

Requirements for a conforming UA:

• The ‘min-width’, ‘max-width’, ‘width’, ‘min-height’, ‘max-height’, and ‘height’ properties must be supported.

• The ‘min-zoom’, ‘max-zoom’, and ‘zoom’ properties must be supported as input to the constraining procedure. However, the UA may choose to use a different zoom factor when presenting the document to the user, and use different minimum and maximum zoom limits for the user interaction.

  This will for instance allow UAs without zooming capabilities to conform and still have interoperable implementations when it comes to viewport dimensions. It will also allow the UA to choose a different zoom factor if the content overflows the actual viewport.

• Support for the ‘user-zoom’ and ‘orientation’ properties is optional.

9. Viewport META element

This section is not normative.

This section describes a mapping from the content attribute of the viewport META element, first implemented by Apple in the iPhone Safari browser, to the properties of the @-o-viewport rule described in this specification.

9.1. Properties

The recognized properties in the viewport META element are:

• width
• height
• initial-scale
• minimum-scale
• maximum-scale
• user-scalable

9.2. Parsing algorithm

Below is an algorithm for parsing the content attribute of the META tag produced from testing Safari on the iPhone. The testing was done on an iPod touch running iPhone OS 4. The UA string of the browser: "Mozilla/5.0 (iPod; U; CPU iPhone OS 4_0 like Mac OS X; en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5 Mobile/8A293 Safari/6531.22.7". The pseudo code notation used is based on the notation used in [Algorithms]. The white-space class contains the following characters (ascii):

• Horizontal tab (0x09)
• Line feed (0x0a)
• Carriage return (0x0d)
• Space (0x20)

Set-Property matches the property names listed in 9.1 case-insensitively. The property-value strings are interpreted as follows:

1. If a prefix of property-value can be converted to a number using strtod, the value will be that number. The remainder of the string is ignored.
2. If the value can not be converted to a number as described above, the whole property-value string will be matched with the following strings case-insensitively: yes, no, device-width, device-height
3. If the string did not match any of the known strings, the value is unknown.

9.3. Translation into @-o-viewport properties

The Viewport META element is placed in the cascade as if it was a <style> element, in the exact same place in the dom, that only contains a single @-o-viewport rule.

Each of the property/value pair from the parsing in the previous section are translated, and added to that single at-rule as follows:

Unknown properties

Unknown properties are dropped.

The width and height properties

The width and height properties are translated into ‘width’ and ‘height’ shorthand properties, effectively setting the min and max properties to the same value.

1. Non-negative number values are translated to pixel lengths
2. Negative number values are translated to ‘auto’
3. device-width and device-height are used as keywords
4. Other keywords and unknown values translate to 0

The initial-scale, minimum-scale, and maximum-scale properties

The properties are translated into ‘zoom’, ‘min-zoom’, and ‘max-zoom’ respectively with the following translations of values.

1. Non-negative number values are translated to <number> values
2. Negative number values are translated to ‘auto’
3. yes is translated to 1.0
4. device-width and device-height are translated to 10
5. no and unknown values are translated to 0

The user-scalable property

The user-scalable property is translated into ‘user-zoom’ with the following value translations.

1. yes and no are translated into ‘zoom’ and ‘fixed’ respectively.
2. Numbers ≥ 1, numbers ≤ -1, device-width and device-height are mapped to ‘zoom’
3. Numbers in the range <-1, 1>, and unknown values, are mapped to ‘fixed’

<meta name="viewport" content="width=480, initial-scale=2.0, user-scalable=1">

@-o-viewport {
  width: 480px;
  zoom: 2.0;
  user-zoom: zoom;
}

10. References

Normative references

[CSS21]

Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 8 September 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-CSS2-20090908

[MEDIAQ]

Håkon Wium Lie; Tantek Çelik; Daniel Glazman. Media Queries. 27 July 2010. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2010/CR-css3-mediaqueries-20100727/

Other references

[Algorithms]

Thomas H. Cormen; et al. Introduction to Algorithms, Second Edition, MIT Press.

Property index

Property	Values	Initial	Percentages	Media
min-width, max-width	<viewport-length>	auto	Refer to the width of the initial viewport at zoom factor 1.0	visual, continuous
width	<viewport-length>{1,2}	See individual properties	See individual properties	visual, continuous
min-height, max-height	<viewport-length>	auto	Refer to the height of the initial viewport at zoom factor 1.0	visual, continuous
height	<viewport-length>{1,2}	See individual properties	See individual properties	visual, continuous
zoom	auto | <number>	auto	The zoom factor itself	visual, continuous
min-zoom	auto | <number>	auto	The zoom factor itself	visual, continuous
max-zoom	auto | <number>	auto	The zoom factor itself	visual, continuous
user-zoom	zoom | fixed	zoom	N/A	visual, continuous
orientation	auto | portrait | landscape	auto	N/A	visual, continuous