<pre class="metadata">

Title: CSS Viewport Module Level 1

Level: 1

Shortname: css-viewport

Group: CSSWG

Status: ED

Prepare for TR: no

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, [email protected], w3cid 106537

Former Editor: Matt Rakow, Microsoft, w3cid 62267

Former Editor: Rune Lillesveen, Opera Software, [email protected]

Former Editor: Ryan Betts, Adobe Systems, [email protected]

Former Editor: Øyvind Stenhaug, Opera Software, [email protected]

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: document, parameters, <viewport-length>

</pre>

<pre class="anchors">

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

</pre>

<pre class="anchors">

spec: fenced-frames; urlPrefix: https://wicg.github.io/fenced-frame/

type: interface; text: FencedFrames

</pre>

<pre class=link-defaults>

spec:webdriver2; type:dfn;

text:error

text:remote end steps

text:success

</pre>

<h2 id="intro">

Introduction</h2>

<div class=non-normative>

<em>This section is not normative.</em>

CSS 2.1 [[!CSS21]] specifies an

<a href="https://www.w3.org/TR/CSS21/visudet.html#containing-block-details">

initial containing block</a> for [=continuous media=] that has the dimensions

of the <a href="https://www.w3.org/TR/CSS21/visuren.html#viewport">

viewport</a>. 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

<a href="https://www.w3.org/TR/CSS21/syndata.html#length-units">recommended</a>

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.

Issue: 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 <a href="http://www.quirksmode.org/blog/archives/2015/09/a_new_device_ad.html">this blog post by ppk</a>

for a good discussion of these issues.

Issue: Various issues about this specification and related specifications

are listed in <a href="https://www.w3.org/Graphics/SVG/WG/wiki/Proposals/Investigation_of_APIs_for_Level_of_detail#The_issues_on_existing_APIs">this report</a>.

</div>

<h2 id="the-viewport">

The viewport</h2>

In CSS 2.1 a <a href="https://www.w3.org/TR/CSS21/visuren.html#viewport">viewport</a>

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

<dl>

<dt><dfn>initial viewport</dfn></dt>

<dd>

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

<dt><dfn>actual viewport</dfn></dt>

<dd>

This is the viewport you get after processing the viewport

<code>&lt;meta&gt;</code> tag.

</dd>

</dl>

ISSUE: 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 <code class=html>&lt;BODY&gt;</code> element of

an HTML or XHTML document. For other document types, it is the

computed 'direction' for the root element.

<h3 id="the-display-feature">Display feature definition</h3>

A <dfn>Display feature</dfn> is a hardware feature that acts as a divider

and creates logically separate region of the viewport called {{segments}}.

It can be a fold area of a device with a foldable screen or a physical

split occupying a logical space within the viewport for example some dual

screen models.

Below is an illustration describing the concept of display features and how

they divide the viewport in {{segments}}:

<img src="display_features_general.svg" width="560" height="258"

alt="Two images, showing two display feature configurations and the respective segments.

One image is showing an vertical display feature, the other is showing

an horizontal display feature" style="width: 70%;height: auto; margin:auto; display: flex;">

<h2 id="viewport-meta">

Viewport <code class=html>&lt;meta&gt;</code> element</h2>

Issue: Specify me

<h3 id="meta-properties">

Properties</h3>

The recognized properties in the viewport

<code class=html>&lt;meta&gt;</code> element are:

<ul>

<li><code class="index" lt="width!!viewport meta">width</code></li>

<li><code class="index" lt="height!!viewport meta">height</code></li>

<li><code class="index">initial-scale</code></li>

<li><code class="index">minimum-scale</code></li>

<li><code class="index">maximum-scale</code></li>

<li><code class="index">user-scalable</code></li>

<li><code class="index">interactive-widget</code></li>

</ul>

<h3 id="parsing-algorithm">

Parsing algorithm</h3>

Below is an algorithm for parsing the <code class=html>content</code>

attribute of the <code class=html>&lt;meta&gt;</code> tag produced

from testing Safari on the iPhone. <span class="note"> The testing was

done on an iPod touch running iPhone OS 4. The UA string of the

browser: <code>"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"</code>.</span> The pseudo code notation

used is based on the notation used in [[Algorithms]].

The whitespace class contains the following characters (ascii):

<ul>

<li>Horizontal tab (0x09)</li>

<li>Line feed (0x0a)</li>

<li>Carriage return (0x0d)</li>

<li>Space (0x20)</li>

</ul>

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:

<ul>

<li>Comma (0x2c)</li>

<li>Semicolon (0x3b)</li>

</ul>

<style>

/* Style for algorithm pseudo code. */

#algorithm {

font-family: serif;

font-size: 1em;

white-space: pre;

margin: 1em;

padding: 1em;

}

#algorithm .method {

counter-reset: statement;

line-height: 1.5em;

}

#algorithm .method-name {

font-variant: small-caps;

}

#algorithm .statement {

counter-increment: statement;

}

#algorithm .statement:before {

content: counter(statement) " ";

display: inline-block;

width: 2em;

}

#algorithm .keyword {

font-weight: bold;

}

</style>

<pre id="algorithm">

<span class="method"><span class="method-name">Parse-Content</span>(<span class="variable">S</span>)</span>

<span class="statement"><span class="variable">i</span> &larr; 1</span>

<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>]</span>

<span class="statement"> <span class="keyword">do</span> <span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] in [whitespace, separator, '=']</span>

<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>

<span class="statement"> <span class="keyword">if</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>]</span>

<span class="statement"> <span class="keyword">then</span> <span class="variable">i</span> &larr; <span class="method-name">Parse-Property</span>(<span class="variable">S</span>, <span class="variable">i</span>)</span>

<span class="method"><span class="method-name">Parse-Property</span>(<span class="variable">S</span>, <span class="variable">i</span>)</span>

<span class="statement"><span class="variable">start</span> &larr; <span class="variable">i</span></span>

<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [whitespace, separator, '=']</span>

<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>

<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> &gt; <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>

<span class="statement"> <span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>

<span class="statement"><span class="variable">property-name</span> &larr; <span class="variable">S</span>[<span class="variable">start</span> .. (<span class="variable">i</span> - 1)]</span>

<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [separator, '=']</span>

<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>

<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> &gt; <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>

<span class="statement"> <span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>

<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] in [whitespace, '=']</span>

<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>

<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> &gt; <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>

<span class="statement"> <span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>

<span class="statement"><span class="variable">start</span> &larr; <span class="variable">i</span></span>

<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [whitespace, separator, '=']</span>

<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>

<span class="statement"><span class="variable">property-value</span> &larr; <span class="variable">S</span>[<span class="variable">start</span> .. (<span class="variable">i</span> - 1)]</span>

<span class="statement"><span class="method-name">Set-Property</span>(<span class="variable">property-name</span>, <span class="variable">property-value</span>)</span>

<span class="statement"><span class="keyword">return</span> <span class="variable">i</span></span>

</pre>

<span class="method-name">Set-Property</span> matches the

<a href="#meta-properties">listed property names</a> case-insensitively.

The <code class="variable">property-value</code> strings are interpreted

as follows:

<ol>

<li>

If a prefix of <code class="variable">property-value</code>

can be converted to a number using <code>strtod</code>, the

value will be that number. The remainder of the string is

ignored.

</li>

<li>

If the value can not be converted to a number as described above,

the whole <code class="variable">property-value</code> string

will be matched with the following strings

case-insensitively: <code class="index">yes</code>,

<code class="index">no</code>, <code class="index" lt="device-width!!viewport meta">device-width</code>,

<code class="index" lt="device-height!!viewport meta">device-height</code>

</li>

<li>

If the string did not match any of the known strings, the

value is unknown.

</li>

</ol>

<h3 id="extend-to-zoom">''extend-to-zoom''</h3>

Issue: Specify extend-to-zoom behavior by the viewport meta tag

<h3 id="interactive-widget-section">''interactive-widget''</h3>

Issue: Move the definition of ''visual viewport'' from CSSOM-View to this spec.

The <dfn export><code>interactive-widget</code></dfn> 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.

<div class="note">The most common such UI widget is a virtual keyboard.</div>

The following is a list of valid values for [=interactive-widget=] and the associated

viewport-resizing behavior:

<dl>

<dt><dfn><code>overlays-content</code></dfn></dt>

<dd>

Interactive UI widgets MUST NOT [=resize=] the [=initial viewport=] nor

the <a spec="CSSOM-VIEW">visual viewport</a>. The user agent must perform the same steps

as when {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to

<code>true</code>.

</dd>

<dt><dfn><code>resizes-content</code></dfn></dt>

<dd>

Interactive UI widgets MUST [=resize=] the [=initial viewport=] by the interactive widget.

<div class="note">

Since the <a spec="CSSOM-VIEW">visual viewport</a>'s size is derived from the

[=initial viewport=], [=resizes-content=] will cause a resize of both the initial and visual

viewports.

</div>

</dd>

<dt><dfn><code>resizes-visual</code></dfn></dt>

<dd>

Interactive UI widgets MUST [=resize=] the <a spec="CSSOM-VIEW">visual viewport</a> but MUST

NOT [=resize=] the <a spec="CSS-VIEWPORT">initial viewport</a>.

</dd>

</dl>

If no value, or an invalid value, is set for [=interactive-widget=], the behavior implied by

[=resizes-visual=] is used as the default.

To <dfn lt="resize">resize a viewport by an interactive widget</dfn>, 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.

<div class="note">

Some examples where the result would non rectangular: a

<a href="https://support.apple.com/en-ca/HT207521">floating or split keyboard</a>, or a keyboard that

<a href="https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/VirtualKeyboardAPI/explainer.md#motivation">

occupies only part</a> of the viewport.

</div>

<h4 id="interaction-with-virtualkeyboard-overlayscontent">

Interaction with virtualKeyboard.overlaysContent

</h4>

[[!VIRTUAL-KEYBOARD]] provides an imperative API to apply the [=overlays-content=] behavior via

the {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} attribute. This attribute

shadows the value set to [=interactive-widget=], namely:

When {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to

<code>true</code>, the UA MUST ignore any value set to [=interactive-widget=] when determining the

resizing behavior of interactive widgets.

When {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to

<code>false</code>, 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|VirtualKeyboard.overlaysContent}} MUST return

only the value previously set to it.

<div class="note">

That is, unless previously set, <code>VirtualKeyboard.overlaysContent</code> returns false

even if <code>interactive-widget=overlays-content</code> is set via the <code>&lt;meta&gt;</code>

tag.

</div>

<pre class=biblio>

{

"Algorithms": {

"authors": [

"Thomas H. Cormen; et al"

],

"title": "Introduction to Algorithms, Second Edition, MIT Press",

"publisher": "MIT Press"

}

}

</pre>

<h2 id='zoom-property'>

The 'zoom' property

</h2>

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 value=]s, 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 <css>auto</css> 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.

<pre class="propdef">

Name: zoom

Value: <<number [0,∞]>> | <<percentage [0,∞]>>

Initial: 1

Applies to: all <<length>> property values of all elements

Inherited: no

Percentages: Converted to <<number>>

Media: visual

Computed value: as specified, but with <<percentage>> converted to the equivalent <<number>>

Animation type: not animatable

</pre>

The values of this property have the following meanings:

<dl dfn-for="zoom" dfn-type=value>

<dt><dfn><<number>></dfn>

<dd>

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.

<dt><dfn><<percentage>></dfn>

<dd>

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.

</dl>

Negative values for 'zoom' are illegal.

<div class="example">

Example of the 'zoom' property applied during hover for magnification effect.

<pre>

&lt;div class="messageBox"&gt;

&lt;div class="label"&gt;Text of the label&lt;/div&gt;

&lt;/div&gt;

&lt;style&gt;

.messageBox {

width: 10em;

padding: 2em;

border: medium solid lightblue;

}

.messageBox:hover {

zoom: 150%;

}

.label {

background: lightgrey;

padding: 1em;

text-align: center;

}

&lt;/style&gt;

</pre>

Here is an llustration of the before and after hover state of the message box element:

<img src="css_zoom_hover_example.png" width="704" height="270"

alt="Two images showing the zooming effect before and after zoom has applied. The second is 1.5 larger.">

</div>

<div class="example">

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

<pre>

&lt;div style="zoom: 2"&gt;

Middle text

&lt;div style="zoom: 2"&gt;

Inner text

&lt;div&gt;

&lt;div&gt;

Outer text

</pre>

</div>

<div class="example">

Example of replaced elements. In this example,

the image and iframe will be twice as large as their default sizing.

<pre>

&lt;div style="zoom: 2"&gt;

&lt;img src="..."&gt;

&lt;iframe src="..."&gt;&lt;/iframe&gt;

&lt;div&gt;

</pre>

</div>

The <dfn export>effective zoom</dfn> of an element is the product of its computed

value of 'zoom' and all flat tree ancestors' computed values of 'zoom'.

The <dfn export>scaled</dfn> value of a CSS length is the [=used value=] of that length;

in particular it includes zoom.

The <dfn export>unscaled</dfn> value of a CSS length relative to an element is the [=scaled=] value divided by the element's [=effective zoom=].

<div class="note">

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

</div>

<h3 id='zoom-om'>

DOM and CSSOM interaction

</h3>

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.

<h2 id=extensions-to-the-window-interface>Extensions to the {{Window}} Interface</h2>

<pre class=idl>

partial interface Window {

[SameObject, Replaceable] readonly attribute Viewport viewport;

};

</pre>

<h2 id="the-viewport-interface">The {{Viewport}} Interface</h2>

<pre class=idl>

[Exposed=Window]

interface Viewport {

readonly attribute FrozenArray&lt;DOMRect>? segments;

};

</pre>

<h2 id='segments'>

The <dfn attribute for=Viewport>segments</dfn> property

</h2>

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 ''<length>/px''.

Additional 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 <a>fully active</a>, 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. If there is only a single viewport segment (typically the size of the {{Viewport}}) return an array with that single segment.

5. Otherwise, return the {{Viewport}}'s [[css-env-1#viewport-segments|segments]] array calculated from the hardware features.

<div class=non-normative>

<em>This section is not normative.</em>

The {{segments}} property represents an immutable snapshot of the device {{segments}} when the value was queried.

If the device state changes (rotation, window resize, <a spec="DEVICE-POSTURE">posture</a> 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.

<div class="example">

If a viewport of 400px by 400px is split horizontally into two side-by-side segments, the {{segments}} array will have the following content:

<code highlight=javascript>[DOMRect(0, 0, 400, 200), DOMRect(0, 200, 400, 200)]</code>

</div>

</div>

<h2 class=no-num id="privacy">Privacy Considerations</h2>

No new privacy considerations have been reported on this specification.

<h2 class=no-num id="security">Security Considerations</h2>

No new security considerations have been reported on this specification.

<h2 class="no-num" id="changes">Appendix A. Changes</h2>

This appendix is <em>informative</em>.

<h3 class="no-num" id="changes-20160329">Since the

<a href="http://www.w3.org/TR/2016/WD-css-device-adapt-1-20160329/">29

March 2016 Working Draft</a>

</h3>

<ul>

<li>Added <css>interactive-widgets</css> property to viewport meta</li>

<li>Removed <css>@viewport</css> rule</li>

<li>Renamed spec from device-adapt to css-viewport</li>

<li>CSSViewportRule exposed to Window</li>

</ul>

<h3 class="no-num" id="changes-20110915">Since the

<a href="https://www.w3.org/TR/2011/WD-css-device-adapt-20110915/">15

September 2011 First Public Working Draft</a>.

</h3>

<ul>

<li>Made various editorial improvements and clarifications.

<li>Added OM Interfaces.

<li>Added semi-colon as separator in meta viewport.

<li>Created UA stylesheets section.

<li>Added recommendation for when to respect orientation property.

<li>Dropped support for the resolution descriptor.

<li>Decouple width/height and zoom, introducing ''extend-to-zoom'' value for meta viewport translation.

<li>Made normative rules about interaction of <css>@viewport</css> and ''@media''.

<li>Allow 0 for <css>&lt;viewport-length&gt;</css> and <css>zoom</css> values

<li>Removed support for device-width/height.

<li>Apply <css>@viewport</css> to top level document only.

<li>Extend [[!CSS3-CONDITIONAL]] rather than CSS21 for nesting in ''@media''.

</ul>

<h2 class="no-num" id="automation">Appendix B. Automation</h2>

<h3 id="automation-segments">Automation of the {{segments}} property</h3>

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 <dfn>display feature override</dfn> is a [=struct=] encapsulating the result of a single display feature.

It has a <dfn data-dfn-for="display feature override">orientation</dfn> (a string that is either "vertical" or "horizontal"),

a <dfn data-dfn-for="display feature override">mask length</dfn> (a positive number describing the length of the feature in CSS ''<length>/px''), and

an <dfn data-dfn-for="display feature override">offset</dfn> (which describe the distance from the origin of the viewport in CSS ''<length>/px'').

<h4 id="internal-slots">Internal slots</h4>

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:

<table class="def">

<thead>

<tr>

<th>

Internal slot

</th>

<th>

Description

</th>

</tr>

</thead>

<tbody>

<tr>

<td>

<dfn data-dfn-for="top-level traversable">\[[DisplayFeaturesOverride]]</dfn>

</td>

<td>

List of [=display feature override=] that overrides those provided by the hardware, or <code>null</code>.

</td>

</tr>

</tbody>

</table>

<h4 id="extension-commands">Extensions Commands</h4>

<h5 id="set-display-features">Set display features</h5>

<table class="def">

<tr>

<th>

HTTP Method

</th>

<th>

[=extension command URI Template|URI Template=]

</th>

</tr>

<tr>

<td>

POST

</td>

<td>

/session/{session id}/displayfeatures

</td>

</tr>

</table>

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

parameter.

<div class=non-normative>

<em>This section is not normative.</em>

This section exists because the input format is not trivial. Here is a pseudo IDL example on

how a [=display feature override=] is defined:

<pre class="idl">

enum OrientationType {

"vertical",

"horizontal"

};

interface DisplayFeature {

readonly attribute OrientationType orientation;

readonly attribute double offset;

readonly attribute double maskLength;

};

</pre>

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

<img src="display_features.svg" width="560" height="258"

alt="Two images showing the meaning of each display feature attributes. One image is showing a vertical display feature, the other is showing an horizontal display feature" style="width: 70%;height: auto; margin:auto; display: flex;">

<div class="example">

To create a [=[[DisplayFeaturesOverride]]=] in the <a spec="WEBDRIVER2">current browsing context</a> of the [=session=] with ID 23,

the [=local end=] would POST to `/session/23/displayfeatures` with the body:

<pre class="lang-json">

{

"features": [

{

"orientation": "horizontal",

"offset": 190,

"maskLength": 20

}

]

}

</pre>

Considering a viewport of 400px by 400px the command will result of a {{segments}} property with the following content:

<code highlight=javascript>[DOMRect(0, 0, 400, 190), DOMRect(0, 210, 400, 190)]</code>

</div>

</div>

<div>

The [=remote end steps=] are:

</div>

<ol>

<li>Let |features| be the result of invoking <a spec="WEBDRIVER2">getting a property</a> "features" from

|parameters|.

</li>

<li>If |features| is not a {{Array}}, return [=error=] with [=error

code|WebDriver error code=] [=invalid argument=].

</li>

<li>Let |parsedFeatures| be a new <a spec=infra>list</a> of [=display feature override=].</li>

<li>For each |feature item| in |features|:

<ol>

<li>If |feature item| is not an {{Object}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].</li>

<li>Let |mask length| be the result of invoking <a spec="WEBDRIVER2">getting a property</a> "maskLength" from |feature item|.</li>

<li>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=].

<li>Let |offset| be the result of invoking <a spec="WEBDRIVER2">getting a property</a> "offset" from |feature item|.</li>

<li>If |offset| is not a {{Number}} or its value is {{Number/NaN}}, +∞, −∞, or negative return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].

<li>Let |orientation| be the result of invoking <a spec="WEBDRIVER2">getting a property</a> "orientation" from |feature item|.</li>

<li>If |orientation| is not a {{string}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].</li>

<li>If |orientation| is neither "vertical" or "vertical", return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].

<li>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=].</li>

<li>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=].</li>

<li>Let |override| be a new [=display feature override=].</li>

<li>Set |override|'s [=mask length=] to |mask length|.</li>

<li>Set |override|'s [=orientation=] to |orientation|.</li>

<li>Set |override|'s [=offset=] to |offset|.</li>

<li>[=list/Append=] |override| to |parsedFeatures|.</li>

</ol>

</li>

<li>Let |topLevelTraversable| be the <a spec="WEBDRIVER2">current browsing context</a>'s

[=browsing context/top-level traversable=].

</li>

<li>Set |topLevelTraversable|.[=[[DisplayFeaturesOverride]]=] to |parsedFeatures|.

</li>

<li>Return [=success=] with data <code>null</code>.

</li>

</ol>

<h5 id="clear-display-features">Clear display features</h5>

<table class="def">

<tr>

<th>

HTTP Method

</th>

<th>

[=extension command URI Template|URI Template=]

</th>

</tr>

<tr>

<td>

DELETE

</td>

<td>

/session/{session id}/displayfeatures

</td>

</tr>

</table>

<div>

This [=extension command=] removes the display features override and returns

control back to hardware.

</div>

<div>

The [=remote end steps=] are:

</div>

<ol>

<li>Let |topLevelTraversable| be the <a spec="WEBDRIVER2">current browsing context</a>'s

[=browsing context/top-level traversable=].

</li>

<li>Set |topLevelTraversable|. [=[[DisplayFeaturesOverride]]=] to <code>null</code>.

</li>

<li>Return [=success=] with data <code>null</code>.

</li>

</ol>