1. Introduction
CSS 2.1 [CSS21] specifies an initial containing block for continuous media that has the dimensions of the viewport. Since the viewport is generally no larger than the display, devices with smaller displays such as phones or tablets typically present a smaller viewport than larger devices like desktop or laptops.
Unfortunately, many documents have historically been designed against larger viewports and exhibit a variety of bugs when viewed in smaller viewports. These include unintended layout wrapping, clipped content, awkward scrollable bounds, and script errors. To avoid these issues, mobile browsers generally use a fixed initial containing block width that mimics common desktop browser window size (typically 980-1024px). The resulting layout is then scaled down to fit in the available screen space.
Although this approach mitigates the issues mentioned above, the downscaling means the CSS pixel size will be smaller than recommended by CSS 2.1. Users will likely need to zoom on the content to view it comfortably.
This mitigation is unnecessary for sites that have been designed to work well on small viewports.
This specification is written from an implementation-centric point of view, making it arguably difficult to read. Significant editorial work may be needed to make it more understandable to different audiences. It also should clarify which viewport is referred to by various js APIs. See this blog post by ppk for a good discussion of these issues.
Various issues about this specification and related specifications are listed in this report.
2. The viewport
In CSS 2.1 a viewport is a feature of a user agent for continuous media and used to establish the initial containing block for continuous media. For paged media, the initial containing block is based on the page area. The page area can be set through @page rules.
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 viewport and the 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 processing the viewport
<meta>tag.
Make actual viewport the layout viewport, define visual viewport.
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.
3. Viewport <meta> element
3.1. Properties
The recognized properties in the viewport <meta> element are:
widthheightinitial-scaleminimum-scalemaximum-scaleuser-scalableinteractive-widget
3.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 whitespace class contains the following characters (ascii):
- Horizontal tab (0x09)
- Line feed (0x0a)
- Carriage return (0x0d)
- Space (0x20)
The recognized separator between property/value pairs is comma for the Safari implementation. Some implementations have supported both commas and semicolons. Because of that, existing content use semicolons instead of commas. Authors should be using comma in order to ensure content works as expected in all UAs, but implementors may add support for both to ensure interoperability for existing content.
The separator class contains the following characters (ascii), with comma as the preferred separator and semicolon as optional:
- Comma (0x2c)
- Semicolon (0x3b)
Parse-Content(S) i ← 1 while i ≤ length[S] do while i ≤ length[S] and S[i] in [whitespace, separator, '='] do i ← i + 1 if i ≤ length[S] then i ← Parse-Property(S, i) Parse-Property(S, i) start ← i while i ≤ length[S] and S[i] not in [whitespace, separator, '='] do i ← i + 1 if i > length[S] or S[i] in [separator] then return i property-name ← S[start .. (i - 1)] while i ≤ length[S] and S[i] not in [separator, '='] do i ← i + 1 if i > length[S] or S[i] in [separator] then return i while i ≤ length[S] and S[i] in [whitespace, '='] do i ← i + 1 if i > length[S] or S[i] in [separator] then return i start ← i while i ≤ length[S] and S[i] not in [whitespace, separator, '='] do i ← i + 1 property-value ← S[start .. (i - 1)] Set-Property(property-name, property-value) return i
Set-Property matches the listed property names case-insensitively.
The property-value strings are interpreted
as follows:
- If a prefix of
property-valuecan be converted to a number usingstrtod, the value will be that number. The remainder of the string is ignored. - If the value can not be converted to a number as described above,
the whole
property-valuestring will be matched with the following strings case-insensitively:yes,no,device-width,device-height - If the string did not match any of the known strings, the value is unknown.
3.3. extend-to-zoom
Specify extend-to-zoom behavior by the viewport meta tag
3.4. interactive-widget
Move the definition of visual viewport from CSSOM-View to this spec.
The interactive-widget property specifies the effect that interactive UI
widgets have on the page’s viewports. It defines whether widgets overlay a given viewport or whether
the viewport is shrunken so that it remains fully visible while the widget is showing. Interactive
UI widgets are transient user agent or operating system UI through which a user can provide input.
The following is a list of valid values for interactive-widget and the associated viewport-resizing behavior:
overlays-content- Interactive UI widgets MUST NOT resize the initial viewport nor
the visual viewport. The user agent must perform the same steps
as when
VirtualKeyboard.overlaysContentis set totrue. resizes-content-
Interactive UI widgets MUST resize the initial viewport by the interactive widget.
Since the visual viewport’s size is derived from the initial viewport, resizes-content will cause a resize of both the initial and visual viewports.
resizes-visual- Interactive UI widgets MUST resize the visual viewport but MUST NOT resize the initial viewport.
If no value, or an invalid value, is set for interactive-widget, the behavior implied by resizes-visual is used as the default.
To resize a viewport by an interactive widget, subtract from it the intersection of the viewport rect with the widget’s OS reported bounding rect. In cases where this would result in a non-rectangular viewport, the behavior is user agent defined.
3.4.1. Interaction with virtualKeyboard.overlaysContent
[VIRTUAL-KEYBOARD] provides an imperative API to apply the overlays-content behavior via
the VirtualKeyboard.overlaysContent attribute. This attribute
shadows the value set to interactive-widget, namely:
When VirtualKeyboard.overlaysContent is set to true, the UA MUST ignore any value set to interactive-widget when determining the
resizing behavior of interactive widgets.
When VirtualKeyboard.overlaysContent is set to false, the UA MUST use the value set to interactive-widget, or the default behavior
if a value is not set, when determining the resizing behavior of interactive widgets.
Getting the value of VirtualKeyboard.overlaysContent MUST return
only the value previously set to it.
VirtualKeyboard.overlaysContent returns false
even if interactive-widget=overlays-content is set via the <meta> tag. Appendix A. Changes
This appendix is informative.
Since the 29 March 2016 Working Draft
- Added interactive-widgets property to viewport meta
- Removed @viewport rule
- Renamed spec from device-adapt to css-viewport
- CSSViewportRule exposed to Window
Since the 15 September 2011 First Public Working Draft.
- Made various editorial improvements and clarifications.
- Added OM Interfaces.
- Added semi-colon as separator in meta viewport.
- Created UA stylesheets section.
- Added recommendation for when to respect orientation property.
- Dropped support for the resolution descriptor.
- Decouple width/height and zoom, introducing extend-to-zoom value for meta viewport translation.
- Made normative rules about interaction of @viewport and @media.
- Allow 0 for <viewport-length> and zoom values
- Removed support for device-width/height.
- Apply @viewport to top level document only.
- Extend [CSS3-CONDITIONAL] rather than CSS21 for nesting in @media.
- Removed @viewport