[css3-exclusions] …message topic…"
Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
CSS exclusions define arbitrary areas around which inline content can flow. CSS exclusions can be defined on any CSS block-level elements.
CSS Shapes control the geometric shapes used for wrapping inline flow content outside or inside an element.
Combining CSS Exclusions and CSS Shapes allows sophisticated layouts, for example having content flow into and/or around circles or other, arbitrarily complex shapes.
This is a public copy of the editors' 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 “css3-exclusions” in the subject, preferably like this: “[css3-exclusions] …summary of comment…”
This document was produced by the CSS Working Group (part of the Style Activity).
This document was produced by a group operating under the 5 February 2004 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.
This is the First Public Working Draft of the CSS Exclusions and Shapes Level 3 Module.
This section is not normative.
The exclusions section of this specification defines features that allow inline flow content to wrap around outside the exclusion area of elements.
The shapes section of the specification defines properties to control the geometry of an element's exclusion area as well as the geometry used for wrapping an element's inline flow content.
Exclusion element
An element that defines an exclusion area
for other elements. The ‘wrap-flow’ property is used to make an
element an exclusion element. An exclusion element contributes its exclusion area to its
containing block's wrapping context
Exclusion area
Interaction of floats and exclusions (Howcome's questions)
The area used for excluding inline flow content around an exclusion
element. The exclusion area is equivalent to the border box
for elements with ‘float’ property
computed to ‘none’ and the margin box
for elements with ‘float’ property
computed to a value other than ‘none’. This specification's ‘shape-outside’
property can be used to define arbitrary, non-rectangular exclusion areas.
Wrapping context
should the wrapping context be generic and include floats?
The wrapping context of an element is a collection of ‘exclusion areas’. The wrapping context is used to
wrap around inline flow content during layout. An element will wrap its
inline flow content in the area that corresponds to the subtraction of its
wrapping context from its own content area.
An element inherits its containing
block's wrapping context unless it specifically resets it using the
‘wrap-through’ property.
Content area
The area used for layout of the inline flow content of an element. By
default the area is equivalent to the content box.
This specification's ‘shape-inside’ property can define
arbitrary, non-rectangular content areas.
Outside and inside
In this specification, ‘outside’ refers to DOM content that is not a
descendant of an element while ‘inside’ refers to the element's descendants.
Exclusion elements define exclusion areas that contribute to their containing block's wrapping context. As a consequence, exclusions impact the layout of their containing block's descendants.
Elements layout their inline content in their content area and avoid the areas in their
associated wrapping context. If the element is itself an exclusion, it
does not wrap around its own exclusion shape and the impact of other
exclusions on other exclusions is controlled by the ‘z-index’ property as explained in the exclusions order section.
The shape properties can is used to change the shape of exclusions.
An element becomes an exclusion when its ‘wrap-flow’
property has a computed value other than ‘auto’.
wrap-flow’
property| Name: | wrap-flow |
|---|---|
| Value: | auto | both | start | end | maximum | clear |
| Initial: | auto |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | as specified, except for floats all values compute to ‘auto’
|
The values of this property have the following meanings:
Setting the ‘wrap-flow’ property to ‘both’, ‘start’, ‘end’, ‘maximum’ or ‘clear’ on an element makes that element an
exclusion element. It's exclusion shape is contributed
to its containing block's wrapping context, causing the containing block's
descendants to wrap around its exclusion area.
The initial value for this property is ‘auto’.
When the property's computed value is ‘auto’, the element does not become an exclusion element unless its ‘float’ property computed value is not
‘none’. In that case, the element
contributes its ‘border box’ to its
containing block's wrapping context and
content flows around it according to the ‘clear’ property.
The element will be considered as an exclusion for all inline flow content descendants of the exclusions' containing block.
Combining exclusions
The above figure illustrates how exclusions are combined. The outermost
box represents an element's content box. The A, B, C and D darker gray
boxes represent exclusions in the element's wrapping context. A, B, C and
D have their respective ‘wrap-flow’ set to ‘both’, ‘start’, ‘end’ and ‘clear’ respectively. The lighter gray areas
show the additional areas that are excluded for inline layout as a result
of the ‘wrap-flow’ value. For example, the area to
the right of ‘B’ cannot be used
for inline layout because the ‘wrap-flow’ for ‘B’ is ‘start’.
The background ‘blue’ area
shows what areas are available for inline content layout. All areas
represented with a light or dark shade of gray are not available for
inline content layout.
Add an example with auto-height content and z-index for exclusions order.
Fluidity of the layout with respect to different amounts of content
The ‘wrap-flow’ property values applied to an
absolutely positioned element.
<style type="text/css">
#exclusion {
position: absolute;
background: lightblue;
border: 3px solid blue;
}
</style>
<div style=”position: relative; border: 1px solid black;”>
<div id=”exclusion”>Donec metus messa, mollis...</div>
Lorem ipsum dolor sit amet...
</div>
#exclusion{ wrap-flow: auto; }
| #exclusion{ wrap-flow: both; }
|
|
|
#exclusion{ wrap-flow: start; }
| #exclusion{ wrap-flow: end; }
|
|
|
#exclusion{ wrap-flow: maximum; }
| #exclusion{ wrap-flow: maximum; }
|
|
|
#exclusion{ wrap-flow: clear; }
|
|
|
An exclusion affects the inline flow content descended from the
exclusion's containing blocks (defined in
CSS 2.1 10.1) and that of all descendant elements of the same
containing block. All inline flow content inside the containing block of
the exclusions is affected. To stop the effect of exclusions defined
outside any element, the ‘wrap-through’ property can be used (see
definition of Propagation of Exclusions below).
wrap-margin’
Property The ‘wrap-margin’ property can be used to
offset the inline flow content wrapping on the outside of exclusions.
Offsets created by the ‘wrap-margin’ property are offset from the
outside of the exclusion. This property takes on positive values only.
| Name: | wrap-margin |
|---|---|
| Value: | <length> |
| Initial: | 0 |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | the absolute length |
wrap-padding’
Property The ‘wrap-padding’ property can be used to
offset to the inline flow content wrapping on the inside of elements.
Offsets created by the ‘wrap-padding’ property are offset from the
content area of the element. This property
takes on positive values only.
| Name: | wrap-padding |
|---|---|
| Value: | <length> |
| Initial: | 0 |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | the absolute length |
wrap-padding’ property affects layout of
content inside the element it applies to while the ‘wrap-margin’
property affects layout of content outside the element.By default, an element inherits its parent wrapping context. In other words it is subject to the exclusions defined outside the element.
Setting the ‘wrap-through’ property to ‘none’ prevents an element from inheriting its
parent wrapping context. In other words, exclusions defined ‘outside’ the element, have not effect on the
element's children layout.
wrap-through’ set to none, or the element
itself, then exclusion still have an effect on the children of that
containing block element.wrap-through’
Propertydo we need wrap-through?
| Name: | wrap-through |
|---|---|
| Value: | wrap | none |
| Initial: | wrap |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | as specified |
The values of this property have the following meanings:
Using the ‘wrap-through’ property to control the
effect of exclusions.
<style type="text/css">
.exclusion {
wrap-flow: both;
position: absolute;
background-color: rgba(220, 230, 242, 0.5);
}
</style>
<div style=”position: relative;”>
<div class=”exclusion”></div>
<div style=”wrap-through: wrap;”> Lorem ipsum dolor sit amet...</div>
<div style=”wrap-through: none;”> Lorem ipsum dolor sit amet...</div>
</div>

wrap’
Shorthand Property| Name: | wrap |
|---|---|
| Value: | <wrap-flow> || <wrap-margin> [ / <wrap-padding>] |
| Initial: | see individual properties |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | see individual properties |
The ‘wrap’
property is a shorthand property for setting the exclusions properties at
the same place in the style sheet.
Exclusions follow the painting order (See [CSS21] Appendix E). Exclusions are
applied in reverse to the document order in which they are defined. The
last exclusion appears on top of all other exclusion, thus it affects the
inline flow content of all other preceding exclusions or elements
descendant of the same containing block. To change the ordering of
exclusions with ‘position’
property computed to a value other than ‘static’, ‘z-index’ can be used. Exclusions with
‘position’ property computed to
‘static’ are not affected by the
‘z-index’ property, thus follow
the painting order.
Ordering of exclusions.
<style type="text/css">
.exclusion {
wrap-flow: both;
position: absolute;
width: 50%;
height: auto;
}
</style>
<div class=”exclusion” style=”top: 0px; left: 0px;”>
Lorem ipsum dolor sit amet...
</div>
<div id="orderedExclusion" class=”exclusion” style=”top: 25%; left: 25%;”>
Lorem ipsum dolor sit amet...
</div>
<div class=”exclusion” style=”top: 50%; left: 50%;”>
Lorem ipsum dolor sit amet...
</div>
#orderedExclusion{ z-index:
auto; }
| #orderedExclusion{ z-index: 1;
}
|
|
|
Is the CSS exclusions processing model incorrect?
Concerns over Error accumulation vs. performance
The rules for exclusions order and exclusions on absolutely positioned elements (particularly those with static position) build this exclusions model on top of the absolute positioning model in CSS Level 2, rather than on top of floats, the existing exclusion model in CSS Level 1 and 2. The CSS Working Group has not reached consensus on whether it intends to base the new exclusions features in this specification on top of absolute positioning (as these sections of this specification do) or on top of floats.
This module does not depend on any particular positioning scheme.
This section illustrates the exclusions processing model with an example. It is meant to be simple. Yet, it contains enough complexity to address the issues of layout dependencies and re-layout.
The code snippet in the following example has two exclusions affecting the document's in-line content.
<html>
<body>
<div id="d1" style="width:100%;height:auto;position:relative">
<p>Lorem ipsusm ...</p>
<p id="e1" style="position:absolute; left:50%; top:50%;
width:40%;height:40%; margin-left:-20%;" ></p>
</div>
<div id="d2" style="width:100%;height:auto;position:static">
<p>Lorem ipsusm ...</p>
<p id="e2" style="position:absolute; right:5ex; top:1em;
width:12ex;height:10em; margin-left:-20%;" ></p>
</div>
</body>
</html>
The following figures illustrates the document's DOM tree, the block boxes generated by the document and the rendering tree for the boxes.
Processing model example: DOM tree
Processing model example: block boxes
Processing model example: box layout tree
The figures illustrate how the boxes corresponding to the element
sometimes have a different containment hierarchy in the layout tree than
in the DOM tree. For example, the block generated by e1 is positioned in its containing block, which is the
d1-block, because e1 is
absolutely positioned and d1 is relatively
positioned. However, while e2 is also absolutely
positioned, its containing block is the initial containing block (ICB).
See the section 10.1 of the CSS 2.1 specification ([CSS21]) for details.
As a result of the computation of containing blocks for the tree, the elements belonging to the wrapping contexts of all the elements can be computed:
e2 element
d1 inherits the body
element's wrapping context and adds the e1
exclusion to it. So the wrapping context is made of both e1 and e2
d2 inherits the body
element's wrapping context.
With the wrapping contexts elements known, layout can start. During that process, the position of exclusions belonging to the wrapping contexts will be computed.
The first step requires positioning the e2
exclusion. This may or many not require laying out other content. In our
example, no content needs to be laid out to compute the e2 exclusion's position. With the exclusion's position
computed, layout can proceed and inline content in the html, body, d1 and d2 elements will flow
around the exclusion.
When laying out d1, the process is similar: the
position of the e1exclusion needs to be computed.
Again, computing the exclusion's position and size may require a layout of
the element. It is the case here because the size and position of e1 depends on resolving the percentage lengths used for
the position and the size. The percentages are relative to the size of
d1 which requires a layout. As a result, in order
to compute a size for d1, a first layout of d1 is done with a wrapping context only containing the
e2 exclusion (whose size and position have been
resolved already). The layout will yield a position and size for e1.
At this point, the wrapping context positions for the d1 wrapping context are fully computed and the final
layout happens: the in-line content wraps around the e1 and e2 exclusions.
The important aspect of the above processing example is that once a first layout (if needed) is done to compute an exclusion's position and size, the position and size of the exclusion is not recomputed if the element's size changes, during a new layout, because of the influence of the exclusion itself. This is what breaks the circular dependency between the layout and the exclusions.
Shapes define arbitrary geometric contours around which or into which
inline flow content flows. There are two different types of shapes –
‘outside’ and ‘inside’. The outside shape defines the exclusion area for an exclusion element. The inside shape defines
an element's content shape and the element's inline content
will flow within that shape.
Note, while the boundaries used for wrapping inline flow content outside and inside an element can be defined using shapes, the actual box model does not change. If the element has specified margins, borders or paddings they will be computed and rendered according to the [[CSS3-Box]] module.
CSS ‘shape’ and CSS box model
relation.
<style type="text/css">
.exclusion {
wrap-flow: both;
position: absolute;
shape-outside: circle(50%, 50%, 50%);
border: 1px solid red;
}
</style>
<div style=”position: relative; border: 1px solid black;”>
<div class=”exclusion”></div>
Lorem ipsum dolor sit amet...
</div>

Shapes can be specified using SVG basic shapes.
The following SVG shapes are supported by the CSS shapes module.
curve’ values
represent rx and ry - define the
rounded rectangles, the x and y axis
and radius of the ellipse used to round off the corners of the
rectangle
If the polygon is not closed the user-agent will automatically add a new vertex at the end.
An SVG shape can be referenced using the url() syntax. The
shape can be any of the SVG
basic shapes or a path
element.
In all cases, percentages are resolved from the border box of the element.
<style>
.in-a-circle {
shape-inside: url(#circle_shape);
}
.in-a-path {
shape-inside: url(#path-shape);
}
</style>
<svg ...>
<circle id="circle_shape" cx="50%x" cy="50%" r="50%" />
<path id="path-shape" d="..." />
</svg>
<div class="in-a-circle">...</div>
<div class="in-a-path">...</div>
When using the SVG syntax or referencing SVG elements to define shapes,
all the lengths expressed in percentages are resolved from the border box
of the element. The coordinate system for the shape has its origin on the
top-left corder of the border box with the x-axis running to the right and
the y-axis running downwards. If the SVG element uses unitless coordinate
values, they are equivalent to using ‘px’ units. If the border box of the element is
dependent on auto sizing (i.e., the element's ‘width’ or ‘height’ property is ‘auto’), then the percentage values are
computed agains ‘0’ and resolve to 0.
Do we need to provide properties to repeat exclusion images as for the background-image property?
Use the contour() keyword. <img id=shape-me
url=foo><style>#shape-me { shape-outside: contour;
}</style> //equal to ‘shape-outside:
url(foo)’ shape-outside: attr(src as url);
Specify what happens with animated images
Another way of defining shapes is by specifying a source image whose
alpha channel is used to compute the inside or outside shape. The shape is
computed to be the path that encloses the area where the opacity of the
specified image is greater than the ‘shape-image-threshold’ value. If the
‘shape-image-threshold’ is not specified,
the initial value to be considered is 0.5.
Note, images can define cavities and inline flow content should wrap inside them. In order to avoid that, another exclusion element can be overlaid.
Shapes are declared with the ‘shape-outside’ or ‘shape-inside’
properties. The ‘shape-outside’ property changes the
geometry of an exclusion
element‘s exclusion are. If the
element is not an exclusion element (see
the ’wrap-flow' property), then the ‘shape-outside’
property has no effect.
The ‘shape-inside’ property defines an
element's content area and the element's
inline flow content wraps into that shape.
shape-outside’
Property| Name: | shape-outside |
|---|---|
| Value: | auto | <shape> | <uri> |
| Initial: | auto |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | computed lengths for <shape>, the absolute URI for <uri>, otherwise as specified |
The values of this property have the following meanings:
rectangle’,‘
circle’, ‘ellipse’
or ‘polygon’.
auto’ had been specified.
Arbitrary shapes for exclusions
The above figure shows how ‘shape-outside’ shapes impact the
exclusion areas. The red box represents an element's content box and
‘A’, ‘B’, ‘C’ and ‘C’ represent exclusions with a complex shape
and their ‘wrap-flow’ property set to ‘both’, ‘start’, ‘end’ and ‘clear’, respectively.
As illustrated in the picture, when an exclusion allows wrapping on all
sides, text can flow inside ‘holes’ in the exclusion (as for exclusion
‘A’). Otherwise, the exclusion
clears the area on the side(s) defined by wrap flow, as illustrated for
‘B’, ‘C’ and ‘D’ above.
shape-inside’
Property The ‘shape-inside’ modifies the shape of the
inner inline flow content from rectangular content box to an arbitrary
geometry.
| Name: | shape-inside |
|---|---|
| Value: | outside-shape | auto | <shape> | <uri> |
| Initial: | outside-shape |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | computed lengths for <shape>, the absolute URI for <uri>, otherwise as specified |
The values of this property have the following meanings:
shape-outside’ property.
rectangle’,‘
circle’, ‘ellipse’
or ‘polygon’.
auto’ had been specified.
shape-image-threshold’ Property The ‘shape-image-threshold’ defines the alpha
channel threshold used to extract the shape using an image. A value of 0.5
means that all the pixels that are more than 50% transparent define the
path of the exclusion shape. The ‘shape-image-threshold’ applies to both
‘shape-outside’ and ‘shape-inside’.
The specified value of ‘shape-image-threshold’ is applied to both
images used for ‘shape-outside’ and ‘shape-inside’.
| Name: | shape-image-threshold |
|---|---|
| Value: | <alphavalue> |
| Initial: | 0.5 |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | alpha channel of the image specified by <uri> |
| Media: | visual |
| Computed value: | The same as the specified value after clipping the <alphavalue> to the range [0.0,1.0]. |
The values of this property have the following meanings:
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.
Conformance to CSS Exclusions and Shapes is defined for three conformance classes:
A style sheet is conformant to CSS Exclusions and Shapes 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 Exclusions and Shapes if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by CSS Exclusions and Shapes 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 Exclusions and Shapes 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.
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.
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.
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.
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:
The specification will remain Candidate Recommendation for at least six months.
This specification is made possible by input from Stephen Zilles, Alexandru Chiculita, Andrei Bucur, Mihnea Ovidenie, Peter Sorotokin, Virgil Palanciuc, Alan Stearns, Arno Gourdol, Eugene Veselov, Arron Eicholz, Alex Mogilevsky, Chris Jones, Marcus Mielke, and the CSS Working Group members.
shape-image-threshold’, 4.3.3.
<alphavalue>’, 4.3.3.
shape-inside’, 4.3.2.
shape-outside’, 4.3.1.
wrap’,
3.3.2.
wrap-flow’, 3.1.1.
wrap-margin’, 3.2.1.
wrap-padding’, 3.2.2.
wrap-through’, 3.3.1.
| Property | Values | Initial | Applies to | Inh. | Percentages | Media |
|---|---|---|---|---|---|---|
| shape-image-threshold | <alphavalue> | 0.5 | block-level elements | no | alpha channel of the image specified by <uri> | visual |
| shape-inside | outside-shape | auto | <shape> | <uri> | outside-shape | block-level elements | no | N/A | visual |
| shape-outside | auto | <shape> | <uri> | auto | block-level elements | no | N/A | visual |
| wrap | <wrap-flow> || <wrap-margin> [ / <wrap-padding>] | see individual properties | block-level elements | no | N/A | visual |
| wrap-flow | auto | both | start | end | maximum | clear | auto | block-level elements | no | N/A | visual |
| wrap-margin | <length> | 0 | block-level elements | no | N/A | visual |
| wrap-padding | <length> | 0 | block-level elements | no | N/A | visual |
| wrap-through | wrap | none | wrap | block-level elements | no | N/A | visual |