CSS Local Viewports Module Level 1

Extensible Web CG's Draft (2012-12-18)

Extensible Web CG's editors:
François REMY, Université Libre de Bruxelles


The specification describes a CSS box model optimized for layout isolation that can guarantee the layout of the descendants of an element do not impact the layout of the element itself nor its ancestors and siblings, like an embedded document does, which enables new optimizations.

Status of this document

This is a public copy of a proposal draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as work in progress.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css-display-viewport” in the subject, preferably like this: “[css-display-viewport] …summary of comment…”.

1. Introduction

This section is not normative.

CSS Layouts have always been exhaustive in the sense the layout of most elements can potentially depend on the layout of every other element in the page, including its own children.

image of a float element modifying the layout of a box outside his scope

This characteristic has an important impact on the layout efficiency: when the DOM tree is modified, the layout of every element of the page may be impacted by the change. In the case of infinitely scrolling list nested in complex web pages, the impact of adding elements in the DOM tree during a scroll event can be highly visible.


The second issue is that it’s impossible to make the layout of some elements depend on the size of a parent element. A very concrete use case for this is user components: the layout of a list view may change from a 2D grid to a 1D list depending on the size it can occupy. This very simple thing is not possible do so using the current CSS layouts because constraints solving would be slow and inefficient.

The third issue is that, when a wrapper or a web component is moved on a web page (expect in some particular and optimized conditions, which depends from browser to browser), the layout/painting of the whole page needs to be recomputed, including the layout of the elements inside the moved element, while their layout should not depend on the position of the wrapper on the page.


To solve those problems, this specification introduces the notion of local viewport.

1.1. Module Interactions

This module defines a new value for the 'display' property defined in CSS 2.1.

1.2. Values

This specification follows the CSS property definition conventions from [CSS21]. Value types not defined in this specification are defined in CSS Level 2 Revision 1 [CSS21]. Other CSS modules may expand the definitions of these value types: for example [CSS3COLOR], when combined with this module, expands the definition of the <color> value type as used in this specification.

1.3. Prior art and workarounds

To solve both problems, a solution already exists: using an <iframe> to host the user component, let it be a scrolling list or anything else (by <iframe> I mean a fixed-size, non-flattened and non-seamless iframe).


Using an iframe solve both problems. Firstly, the layout inside the <iframe> is independent of the layout outside the iframe. When an iframe is moved, if its dimension doesn’t change, the layout of the document inside the iframe doesn’t have to be recomputed. Also, even when the dimension of the iframe changes, the layout of the document inside the iframe can be delayed and doesn’t impact the layout of the outer document. Last but not least, if the DOM tree inside the frame changes, it doesn't force a relayout of the outer document.

Naturally, the limitation imposed by this setting (in terms of layout) is that the size of the iframe must not depend on the layout of its content (even if seamless iframes have already lifted some of those restrictions, and even if scripts from the inner document have the potential to retroact on the parent iframe element, something that was already done in the past to polyfill seamless iframes).

The problem with this approach is that it consumes a lot of memory (new document, new JavaScript hierarchy, new security context, ...) and add marshalling costs when you decide to transmit information between frames; also event bubbling get really messed up. All this is really complex to manage and requires huge frameworks and experience to balance the things correctly.

2. Definitions

2.1. Local Viewport

A local viewport host is a leaf node of the layout tree from which a new layout tree is spawned (whose root is called the local viewport root and whose children are the children that would have been put in the local viewport host otherwhise). That shadow layout tree is independent from the one it has been spawned, even if they share the same browsing context.

To the contrary of the case of an iframe, the new context applies to CSS and to the layout engine only, and not to the real DOM; it doesn't create a nested browsing context either. From a scripting point of view, there's no visible difference between an element inside or outside the local viewport.

It is possible to combine a local viewport with a Shadow DOM to get both Layout and DOM isolation. It's suspected that a lot of web components will actually use this to improve their layout performance (and be isolated from the document in which they are inserted).

Local viewports can take advantage of multi-cores processors by running the layout of independent viewports on different threads: on the following example, the root element is divided into 4 viewports (à la frameset) which make it possible to do the layout of the page on 4 independent threads.

If only one section of the page is not responding fast enough for a 60fps frame rate, it's still possible to reuse the last calculated rendering for that section and still get 60fps rendering for the rest of the page.

Inside a local viewport, a new layout context is applied as if the element in the spawned layout tree were hosted in a different viewport whose dimensions match the ones of the local viewport host.

That means that, for example, the value of CSS counters are not shared between a viewport and its local viewports. It's possible, however, to maintain the relationship by script using counter-reset, if this is necessary.

2.1. Parent Viewport

The parent viewport of an element is the viewport host of the layout tree in which an element is rendered. If there's no such element, the parent viewport of the element is the viewport defined in the section 9.1 of the CSS 2.1 specification.

As long as the parent viewport of an element is not resized and its content & styles are not modified, the layout of an element should not be recomputed.

3. Syntax and implementations

3.1. Creating a local viewport

An element or a pseudo-element is represented with a local viewport host in the layout tree if its 'display' property has the 'viewport' value.

3.2. Layout of a local viewport

The local viewport host on the main document is rendered as usual in its viewport context, except that it doesn't have any child. Whenever the local viewport host should be rendered, the render of the local viewport root is painted instead of its actual content.

The local viewport root inherits the computed value of its overflow property from the local viewport host it's attached to. The children of the local viewport root are rendered as if they were direct child of the root element of the viewport.

When rendered, the content of the viewport is clipped to the dimensions of the parent local viewport host border box. This restriction is necessary to make sure that the painted area of a viewport host is not dependent of its content.

What to do if 'height: auto' is specified on a local viewport host? If we follow the current algorithm, auto will result in an 0px height (because the element is seen as having no children from the parent viewport). An option would be to resolve this by using the same algorithm as a seamless iframe does in HTML5.

How to specify the layout manager in application inside a viewport element?

We could-use a viewport-display property for the purpose, of transform modify the grammar to accept (<display-outside> <display-type>? <display-inside> | <display-shortname>) where <display-viewport> can be either 'viewport' or 'auto' (the latter being the default value).

Tab Atkins also proposed a new layout manager where the viewports can only have very specific, optimized layout modes but I don't think this is a good idea to force that as the only possibility (the mean use case of a viewport is really to isolate the layout of a part of the DOM tree, not to force a particular layout mode)


This section is empty and is a work in progress.

I would also like, for scripting purpose, to get the ‘resize’ event working on the viewport elements (in fact, I would like it to work on any element, but at least on viewport elements this is critical). This event is important for case of web components that should be able to perform actions when their size changes.

It’s interesting to note that the ‘resize’ event already work on all elements (firing when their width/height changes) on Internet Explorer since version 5.5 so this is reasonable to think it’s possible to implement it (even if it has been deprecated in IE10 because the event don’t work totally correctly in the case of CSS transitions and animations).

5. Conformance

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

5.2. Conformance Classes

Conformance to CSS Local Viewports is defined for three conformance classes:

style sheet
A CSS style sheet.
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 CSS Local Viewports if all of its declarations that use properties defined in this module have values that are valid according to the generic CSS grammar and the individual grammars of each property as given in this module.

A renderer is conformant to CSS Local Viewports if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by CSS Local Viewports 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 CSS Local Viewports Module 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.

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

5.4. Experimental Implementations

To avoid clashes with future CSS features, the CSS2.1 specification reserves a prefixed syntax for proprietary and experimental extensions to CSS.

Prior to a specification reaching the Candidate Recommendation stage in the W3C process, all implementations of a CSS feature are considered experimental. The CSS Working Group recommends that implementations use a vendor-prefixed syntax for such features, including those in W3C Working Drafts. This avoids incompatibilities with future changes in the draft.

5.5. 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 http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

5.6. CR Exit Criteria

For this specification to be advanced to Proposed Recommendation, there must be at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products, there is no requirement that all features be implemented by a single product. For the purposes of this criterion, we define the following terms:

each implementation must be developed by a different party and cannot share, reuse, or derive from code used by another qualifying implementation. Sections of code that have no bearing on the implementation of this specification are exempt from this requirement.
passing the respective test case(s) in the official CSS test suite, or, if the implementation is not a Web browser, an equivalent test. Every relevant test in the test suite should have an equivalent test created if such a user agent (UA) is to be used to claim interoperability. In addition if such a UA is to be used to claim interoperability, then there must one or more additional UAs which can also pass those equivalent tests in the same way for the purpose of interoperability. The equivalent tests must be made publicly available for the purposes of peer review.
a user agent which:
  1. implements the specification.
  2. is available to the general public. The implementation may be a shipping product or other publicly available version (i.e., beta version, preview release, or “nightly build”). Non-shipping product releases must have implemented the feature(s) for a period of at least one month in order to demonstrate stability.
  3. is not experimental (i.e., a version specifically designed to pass the test suite and is not intended for normal usage going forward).

The specification will remain Candidate Recommendation for at least six months.


Thanks to Tab Atkins and Boris Zbarsky for their help.

Thanks also to all the persons who contributed to this draft via www-style or any other mean.


Normative references

Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-CSS2-20110607
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

Other references

Håkon Wium Lie; Bert Bos. Cascading Style Sheets (CSS1) Level 1 Specification. 11 April 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-CSS1-20080411
L. David Baron. CSS Syntax Module Level 3. 13 August 2003. W3C Working Draft. URL: http://www.w3.org/TR/css3-syntax/
Tantek Çelik; Chris Lilley; L. David Baron. CSS Color Module Level 3. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-css3-color-20110607


Property index

Property Values Initial Applies to Inh. Computed value Media