CSS Viewport Module Level 1

W3C First Public Working Draft,

More details about this document
This version:
https://www.w3.org/TR/2024/FPWD-css-viewport-1-20240712/
Latest published version:
https://www.w3.org/TR/css-viewport-1/
Editor's Draft:
https://drafts.csswg.org/css-viewport-1/
Previous Versions:
History:
https://www.w3.org/standards/history/css-viewport-1/
Feedback:
CSSWG Issues Repository
CSSWG GitHub
Inline In Spec
Editors:
Florian Rivoal (Invited Expert)
(Mozilla)
Former Editors:
Matt Rakow (Microsoft)
(Opera Software)
(Adobe Systems)
(Opera Software)
Suggest an Edit for this Spec:
GitHub Editor

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

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

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the CSS Working Group as a First Public Working Draft using the Recommendation track. Publication as a First Public Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “css-viewport” in the title, like this: “[css-viewport] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list [email protected].

This document is governed by the 03 November 2023 W3C Process Document.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

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. 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

Specify me

3.1. Properties

The recognized properties in the viewport <meta> element are:

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):

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:

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:

  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.

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 most common such UI widget is a virtual keyboard.

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.overlaysContent is set to true.
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.

Some examples where the result would non rectangular: a floating or split keyboard, or a keyboard that occupies only part of the viewport.

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.

That is, unless previously set, VirtualKeyboard.overlaysContent returns false even if interactive-widget=overlays-content is set via the <meta> tag.

4. The zoom property

An element becomes zoomed when the zoom property has a positive computed value different than 1 (or when a flat tree ancestor has zoom).

To apply zoom, the used value of a CSS property (including values inside of path() strings) is pre-multiplied (before any other steps in the used value stage) by the used value of zoom for the element. It also multiplies the natural size of all replaced elements, background images, and nested frames (except for fenced frames [FENCED-FRAME]) by the used value of zoom.

Note: This results in a magnification or minification effect.

Note: Since this multiplication is on computed values, it applies to all inherited properties such as line-height and font-size.

Nested values of zoom multiply, resulting in additional scaling of <length> values. The used value for zoom is always its effective zoom.

The zoom property has no effect on <length> property values with computed values that are auto or <percentage>.

Note: Unlike transform, scaling the zoom property affects layout.

Note: The computed value of font-size is never <percentage>; thus zoom always applies.

Note: zoom does not affect or prevent transform scaling.

Name: zoom
Value: <number [0,∞]> || <percentage [0,∞]>
Initial: 1
Applies to: all <length> property values of all elements
Inherited: no
Percentages: Converted to <number>
Computed value: as specified, but with <percentage> converted to the equivalent <number>
Canonical order: per grammar
Animation type: not animatable
Media: visual

The values of this property have the following meanings:

<number>
Positive floating point number indicating a zoom factor. Numbers smaller than 1.0 indicate a "zoom out" or minification effect, while numbers greater than 1.0 indicate a "zoom in" or magnification effect. A 0 value is treated as if it was 1.

Note: The treatment of 0 is a web compatibility quirk.

<percentage>
Positive floating point number, followed by a percentage character ("%") which indicates a zoom factor multiplied by 100. A 0 percentage is treated as if it was 100%.

Note: The treatment of 0 is a web compatibility quirk.

Negative values for zoom are illegal.

Example of the zoom property applied during hover for magnification effect. 
<div class="messageBox">
  <div class="label">Text of the label</div>
</div>

<style>
.messageBox {
    width: 10em;
    padding: 2em;
    border: medium solid lightblue;
}

.messageBox:hover {
    zoom: 150%;
}

.label {
    background: lightgrey;
    padding: 1em;
    text-align: center;
}
</style>

Here is an llustration of the before and after hover state of the message box element: Two images, showing the zooming effect before and after zoom has applied. The second is 1.5 larger.

Example of nested zoom. In this example, "Inner text" is 4x as large as "Outer text", and "Middle text" is 2x as large as "Outer text". 
<div style="zoom: 2">
  Middle text
  <div style="zoom: 2">
     Inner text
  <div>
<div>
Outer text
Example of replaced elements. In this example, the image and iframe will be twice as large as their default sizing. 
<div style="zoom: 2">
  <img src="...">
  <iframe src="..."></iframe>
<div>

The effective zoom of an element is the product of its computed value of zoom and all flat tree ancestors' computed values of zoom.

The scaled value of a CSS length is the used value of that length; in particular it includes zoom.

The unscaled value of a CSS length relative to an element is the scaled value divided by the element’s effective zoom.

The effective zoom of an element in a nested frame may be a value other than 1 even if zoom is never set on an element in that frame. This can be observed by authors via APIs such as devicePixelRatio and getBoundingClientRect.

4.1. DOM and CSSOM interaction

Computed style APIs (i.e., all values returned by getComputedStyle()) that are non-auto and non-percentage lengths must be unscaled.

The getBoundingClientRect, getClientRects, and IntersectionObserver APIs must return rects with scaled lengths.

All other APIs related to element geometries must return unscaled lengths (except as detailed below). This is explained in detail in CSSOM View § 7 Extensions to the HTMLElement Interface.

In cases where properties (such as scrollTop) are propagated to the viewport, APIs for these lengths must be in viewport units, and not be divided by the zoom of the element.

The devicePixelRatio of a frame is multiplied by the effective zoom inherited by its parent frame.

5. Extensions to the Window Interface

partial interface Window {
[SameObject, Replaceable] readonly attribute Viewport viewport;
};

6. Viewport

6.1. The Viewport Interface

[Exposed=Window]
interface Viewport {
  readonly attribute FrozenArray<DOMRect>? segments;
};

7. The segments property

The segments property is an array of DOMRect that represent the dimensions of each existing viewport segment. Each DOMRect contains the geometry of the segment (x, y, width, height) in CSS px.

Additonal details about the definition of a viewport segment can be found here: CSS Environment Variables 1 § 2.2 Viewport segment variables.

The segments attribute must run these steps:

  1. If the Viewport's associated Document is not fully active, return null.

  2. Returns null if there is only a single viewport segment and abort these steps.

  3. Otherwise, return the Viewport's segments array.

This section is not normative.

The segments property represents an immutable snapshot of the device segments when the value was queried. If the device state changes (rotation, window resize, posture change), the value previously retrieved will be invalid. Developers can listen to Screen Orientation, Window Resize, or Posture changes events to detect device state changes.

If a viewport of 400px by 400px is split horizontally into two side-by-side segments, the segments array will have the following content: [DOMRect(0, 0, 400, 200), DOMRect(0, 200, 400, 200)]

Appendix A. Changes

This appendix is informative.

Since the 29 March 2016 Working Draft

Since the 15 September 2011 First Public Working Draft.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at https://www.w3.org/Style/CSS/Test/. Questions should be directed to the [email protected] mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-ENV-1]
CSS Environment Variables Module Level 1. Editor's Draft. URL: https://drafts.csswg.org/css-env-1/
[CSS-IMAGES-3]
Tab Atkins Jr.; Elika Etemad; Lea Verou. CSS Images Module Level 3. 18 December 2023. CR. URL: https://www.w3.org/TR/css-images-3/
[CSS-PAGE-3]
Elika Etemad. CSS Paged Media Module Level 3. 14 September 2023. WD. URL: https://www.w3.org/TR/css-page-3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 12 March 2024. WD. URL: https://www.w3.org/TR/css-values-4/
[CSS-VIEWPORT-1]
Florian Rivoal; Emilio Cobos Álvarez. CSS Viewport Module Level 1. 25 January 2024. WD. URL: https://www.w3.org/TR/css-viewport-1/
[CSS-WRITING-MODES-3]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 3. 10 December 2019. REC. URL: https://www.w3.org/TR/css-writing-modes-3/
[CSS21]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: https://www.w3.org/TR/CSS21/
[CSS3-CONDITIONAL]
Chris Lilley; David Baron; Elika Etemad. CSS Conditional Rules Module Level 3. 15 August 2024. CR. URL: https://www.w3.org/TR/css-conditional-3/
[CSSOM-1]
Daniel Glazman; Emilio Cobos Álvarez. CSS Object Model (CSSOM). 26 August 2021. WD. URL: https://www.w3.org/TR/cssom-1/
[CSSOM-VIEW-1]
Simon Pieters. CSSOM View Module. 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-view-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[FENCED-FRAME]
Fenced Frame. Draft Community Group Report. URL: https://wicg.github.io/fenced-frame/
[GEOMETRY-1]
Simon Pieters; Chris Harrelson. Geometry Interfaces Module Level 1. 4 December 2018. CR. URL: https://www.w3.org/TR/geometry-1/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INTERSECTION-OBSERVER]
Stefan Zager; Emilio Cobos Álvarez; Traian Captan. Intersection Observer. 18 October 2023. WD. URL: https://www.w3.org/TR/intersection-observer/
[MEDIAQUERIES-5]
Dean Jackson; et al. Media Queries Level 5. 18 December 2021. WD. URL: https://www.w3.org/TR/mediaqueries-5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[VIRTUAL-KEYBOARD]
Anupam Snigdha. VirtualKeyboard API. 5 May 2022. WD. URL: https://www.w3.org/TR/virtual-keyboard/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[Algorithms]
Thomas H. Cormen; et al. Introduction to Algorithms, Second Edition, MIT Press.
[CSS-TRANSFORMS-1]
Simon Fraser; et al. CSS Transforms Module Level 1. 14 February 2019. CR. URL: https://www.w3.org/TR/css-transforms-1/
[CSS22]
Bert Bos. Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification. 12 April 2016. WD. URL: https://www.w3.org/TR/CSS22/
[DEVICE-POSTURE]
Diego Gonzalez-Zuniga; Kenneth Christiansen; Alexis Menard. Device Posture API. 20 November 2024. WD. URL: https://www.w3.org/TR/device-posture/
[SCREEN-ORIENTATION]
Marcos Caceres. Screen Orientation. 9 August 2023. WD. URL: https://www.w3.org/TR/screen-orientation/

Property Index

Name Value Initial Applies to Inh. %ages Anim­ation type Canonical order Com­puted value Media
zoom <number [0,∞]> || <percentage [0,∞]> 1 all <length> property values of all elements no Converted to <number> not animatable per grammar as specified, but with <percentage> converted to the equivalent <number> visual

IDL Index

partial interface Window {
[SameObject, Replaceable] readonly attribute Viewport viewport;
};

[Exposed=Window]
interface Viewport {
  readonly attribute FrozenArray<DOMRect>? segments;
};

Issues Index

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. ↵
Make actual viewport the layout viewport, define visual viewport. ↵
Specify me ↵
Specify extend-to-zoom behavior by the viewport meta tag ↵
Move the definition of visual viewport from CSSOM-View to this spec. ↵