Title: CSS Viewport Module Level 1
Level: 1
Shortname: css-viewport
Group: CSSWG
Status: FPWD
Date: 2024-01-25
Prepare for TR: yes
Work Status: Exploring
TR: http://www.w3.org/TR/css-viewport-1/
ED: https://drafts.csswg.org/css-viewport-1/
Previous Version: http://www.w3.org/TR/2016/WD-css-device-adapt-1-20160329/
Editor: Florian Rivoal, Invited Expert, https://florian.rivoal.net, w3cid 43241
Editor: Emilio Cobos Álvarez, Mozilla, emilio@mozilla.com, w3cid 106537
Former Editor: Matt Rakow, Microsoft, w3cid 62267
Former Editor: Rune Lillesveen, Opera Software, rune@opera.com
Former Editor: Ryan Betts, Adobe Systems, rbetts@adobe.com
Former Editor: Øyvind Stenhaug, Opera Software, oyvinds@opera.com
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.
Issue Tracking: CSSWG GitHub https://github.com/w3c/csswg-drafts/labels/css-viewport-1
Ignored Vars: 

spec: virtual-keyboard; urlPrefix: https://w3c.github.io/virtual-keyboard
	type: interface; text: VirtualKeyboard; url: dom-virtualkeyboard
	type: attribute; text: overlaysContent; for: VirtualKeyboard; url: dom-virtualkeyboard-overlayscontent

spec: fenced-frames; urlPrefix: https://wicg.github.io/fenced-frame/
	type: interface; text: FencedFrames

	spec:webdriver2; type:dfn; text:remote end steps
	spec:webdriver2; type:dfn; text:error

Introduction

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

Display feature definition

Viewport <meta> element

Properties

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

Parsing algorithm

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

• 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

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.

''extend-to-zoom''

''interactive-widget''

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

Interaction with virtualKeyboard.overlaysContent

{
	"Algorithms": {
		"authors": [
			"Thomas H. Cormen; et al"
		],
		"title": "Introduction to Algorithms, Second Edition, MIT Press",
		"publisher": "MIT Press"
	}
}

The 'zoom' property

> values. The [=used value=] for zoom is always its [=effective zoom=]. The 'zoom' property has no effect on <> property values with computed values that are 'auto' or <>. Note: Unlike 'transform', scaling the 'zoom' property affects layout. Note: The computed value of 'font-size' is never <>; thus 'zoom' always applies. Note: 'zoom' does not affect or prevent 'transform' scaling.

	Name: zoom
	Value: <> || <>
	Initial: 1
	Applies to: all <> property values of all elements
	Inherited: no
	Percentages: Converted to <>
	Media: visual
	Computed value: as specified, but with <> converted to the equivalent <>
	Animation type: not animatable

The values of this property have the following meanings:

<>

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.

<>

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:

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 {{Window/devicePixelRatio}} and {{Element/getBoundingClientRect}}.

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 {{Element/getBoundingClientRect}}, {{Element/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#extensions-to-the-htmlelement-interface]]. In cases where properties (such as {{Element/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 {{Window/devicePixelRatio}} of a frame is multiplied by the [=effective zoom=] inherited by its parent frame.

Extensions to the {{Window}} Interface

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

Viewport

The {{Viewport}} Interface

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

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-env-1#viewport-segments]]. The {{segments}} attribute getter steps are: 1. If the {{Viewport}}'s associated {{Document}} is not fully active, return null. 2. Let |topLevelTraversable| be |document|'s [=relevant global object=]'s [=/navigable=]'s [=browsing context/top-level traversable=]. 3. If |topLevelTraversable|.[=[[DisplayFeaturesOverride]]=] is non-null, return {{Viewport}}'s [[css-env-1#viewport-segments|segments]] array calculated from |topLevelTraversable|.[=[[DisplayFeaturesOverride]]=]. 4. Returns null if there is only a single viewport segment and abort these steps. 5. Otherwise, return the {{Viewport}}'s [[css-env-1#viewport-segments|segments]] array calculated from the hardware features.

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 {{ScreenOrientation/onchange|Screen Orientation}}, {{Window/resize|Window Resize}}, or {{DevicePosture/onchange|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

• 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 <> and '@viewport/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

Appendix B. Automation

Automation of the {{segments}} property

The {{segments}} property poses a challenge to test authors, as exercising this property requires access to specific hardware devices. To address this challenge this document defines [[WEBDRIVER2]] [=extension commands=] that allow users to control how the viewport is split by one or more [=display feature| display features=] (such as a fold or a hinge between two separate displays). A display feature override is a [=struct=] encapsulating the result of a single display feature. It has a orientation (a string that is either "vertical" or "horizontal"), a mask length (a positive number describing the length of the feature in CSS ''/px''), and an offset (which describe the distance from the origin of the viewport in CSS ''/px'').

Internal slots

To support the [=extension commands=] below and their integration with the {{segments}} attribute getter steps, [=browsing context/top-level traversables=] must have the following internal slots:

Internal slot	Description
\[[DisplayFeaturesOverride]]	List of [=display feature override=] that overrides those provided by the hardware, or null.

Extensions Commands

Set display features

HTTP Method	[=extension command URI Template|URI Template=]
POST	/session/{session id}/displayfeatures

This [=extension command=] creates a setup that emulates a set of [=display feature override=] by taking a list of display features as parameter.

This section is not normative. This section exists because the input format is not trivial. Here is a pseudo IDL example on how a [=display feature override=] is defined:

		enum OrientationType {
			"vertical",
			"horizontal"
		};

		interface DisplayFeature {
			readonly attribute OrientationType orientation;
			readonly attribute double offset;
			readonly attribute double maskLength;
		};
	

Below is an illustration showing the various properties of a display feature:

To create a [=[[DisplayFeaturesOverride]]=] in the current browsing context of the [=session=] with ID 23, the [=local end=] would POST to `/session/23/displayfeatures` with the body:

		{
			"features": [
				{
					"orientation": "horizontal",
					"offset": 190,
					"maskLength": 20
				}
			]
		}
		

Considering a viewport of 400px by 400px the command will result of a {{segments}} property with the following content: [DOMRect(0, 0, 400, 190), DOMRect(0, 210, 400, 190)]

The [=remote end steps=] are:

1. Let |features| be the result of invoking getting a property "features" from |parameters|.
2. If |features| is not a {{Array}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
3. Let |parsedFeatures| be a new list of [=display feature override=].
4. For each |feature item| in |features|:
   1. If |feature item| is not an {{Object}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
   2. Let |mask length| be the result of invoking getting a property "maskLength" from |feature item|.
   3. If |mask length| is not a {{Number}} or its value is {{Number/NaN}}, +∞, −∞, or negative return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
   4. Let |offset| be the result of invoking getting a property "offset" from |feature item|.
   5. If |offset| is not a {{Number}} or its value is {{Number/NaN}}, +∞, −∞, or negative return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
   6. Let |orientation| be the result of invoking getting a property "orientation" from |feature item|.
   7. If |orientation| is not a {{string}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
   8. If |orientation| is neither "vertical" or "vertical", return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
   9. If |orientation| is "vertical" and |mask length| + |offset| is greater than viewport width including the size of the rendered scrollbar, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
   10. If |orientation| is "vertical" and |mask length| + |offset| is greater than viewport height including the size of the rendered scrollbar, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
   11. Let |override| be a new [=display feature override=].
   12. Set |override|'s [=mask length=] to |mask length|.
   13. Set |override|'s [=orientation=] to |orientation|.
   14. Set |override|'s [=offset=] to |offset|.
   15. [=list/Append=] |override| to |parsedFeatures|.
5. Let |topLevelTraversable| be the current browsing context's [=browsing context/top-level traversable=].
6. Set |topLevelTraversable|.[=[[DisplayFeaturesOverride]]=] to |parsedFeatures|.
7. Return [=success=] with data null.

Clear display features

HTTP Method	[=extension command URI Template|URI Template=]
DELETE	/session/{session id}/displayfeatures

This [=extension command=] removes the display features override and returns control back to hardware.

The [=remote end steps=] are:

1. Let |topLevelTraversable| be the current browsing context's [=browsing context/top-level traversable=].
2. Set |topLevelTraversable|. [=[[DisplayFeaturesOverride]]=] to null.
3. Return [=success=] with data null.