Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
CSS Exclusions extend the concept of CSS floats (see [CSS21]): they provide the ability to exclude arbitrary areas around which inline content can flow. Unlike CSS floats, exclusions can be applied to positioned elements.
CSS Shapes allow changing the geometric shape of elements used for wrapping inline flow content outside or inside the 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 section is not normative.
We start by defining features that allow inline flow content to wrap around outside the border box of elements. The term "exclusion" refers to elements whose exterior is used to wrap inline flow content.
Further, shapes allow changing the geometry of the contour used for wrapping inline flow content outside or inside an element.
This module does not replace or extend any prior CSS modules.
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.
In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the inherit keyword as their property value. For readability it has not been repeated explicitly.
Exclusions are elements that will be avoided by the user agent when laying out inline flow content outside of them. The exclusion area is computed relative to the outside border box of the element on which the exclusion is specified. The shape properties can be used to change the shape of exclusions. Exclusions establish a wrapping context for all inline flow content descendants of their containing block.
Note,
‘Outside
’ is referring to content
in DOM that is not a descendant of the element on which the ‘wrap-flow
’ was
specified. ‘Inside
’ is referring
to the content descendant of an element.
To define an element as an
exclusion, the ‘wrap-flow
’ property must be specified to a
value other than ‘auto
’.
wrap-flow
’
Property Setting the ‘wrap-flow
’
property to ‘both
’, ‘left
’, ‘right
’, ‘maximum
’ or ‘clear
’ enables the exclusion inline flow
content wrapping features, causing outside content to wrap around its
border box. The initial value for this property is ‘auto
’, in this case the element will not be
considered for wrapping inline flow content unless the ‘float
’ property is specified to a value other
than ‘clear
’.
The element will be considered an exclusion for all inline flow content descendent of the exclusions' containing block.
Name: | wrap-flow |
---|---|
Value: | auto | both | left | right | 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:
Note, Floats are
considered exclusions for compatibility and ‘wrap-flow
’
computes to ‘auto
’ when the
‘float
’ property is anything other
than ‘clear
’.
wrap-flow: auto 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: left; }
| #exclusion{ wrap-flow: right; }
|
![]() | ![]() |
#exclusion{ wrap-flow: maximum; }
| #exclusion{ wrap-flow: clear; }
|
![]() | ![]() |
Exclusions affect the
inline flow content inside of their containing blocks (defined in CSS
2.1 10.1) and that of all descendent 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 |
Content Area
The area used for layout of
the inline flow content of an element. By default the area is equivalent
to the [CSS21]
content box. This specification modifies this definition by the
introduction of ‘shape-inside
’ property.
Exclusions can be used to
wrap all inline flow content within all descendants of the containing
block of the exclusion. In order to prevent wrapping of inline flow
content on any element around exclusions, the ‘wrap-through
’
property can be used. Setting the property to ‘none
’ will prevent the wrapping of inline flow
content around exclusion elements defined outside. The ‘wrap-through
’
property does not have an effect over exclusions contained inside the
element.
wrap-through
’
PropertyName: | 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:
wrap-through - controlling 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 PropertyName: | 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 exclusoins properties at the same place
in the style sheet.
The ordering of exclusions follows the visual order. 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 descendent of the same containing block. To change the ordering of positioned exclusions, z-index can be used.
Ordering of exclusions
<style type="text/css">
.exclusion {
wrap-flow: both;
position: absolute;
width: 50%;
height: 50%;
}
</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;
}
|
![]() | ![]() |
This section is not normative.
Exclusions can be specified on positioned elements and elements can be positioned from their static position. Since, the static position of such elements depends on the inline flow content affected by the exclusion itself; there is a circular dependency between the two layout tasks. To break this circular dependency a two-pass layout approach is recommended. The first layout pass computes the static positions of all auto-positioned exclusions by laying out all content besides exclusions. The second pass is layout of all elements including all exclusions. Exclusions that depend on their static position will use the position calculated during the first layout pass.
Note, this may cause exclusions to overlap or be distant from their static position (compared to non-exclusions auto-positioned elements).
Similar dependency exists
for exclusions whose size or position is specified in percentage and their
containing block size is specified as ‘auto
’. In such cases the size or position of
the exclusion is calculated based on the size of the containing block
calculated in the first layout pass.
Since exclusions can be positioned on all levels of nested elements, if layout is restarted on every level of nesting, the time to complete layout will be exponential. To avoid such multiplicity of layout passes, the restart of the second layout pass should be scoped to the top-most containing block of exclusions. Similarly, restarting layout for the entire document is not necessary unless there are exclusions whose containing block is the initial containing block.
Shapes are used to define
arbitrary geometric contours around which inline flow content flows. There
are two different types of shapes – ‘outside
’ and ‘inside
’. The outside shape is used for
wrapping inline flow content around exclusions. The inside shape is used
for wrap inline flow content of flow
container elements.
Flow Container
A flow container is an
element with a ‘display
’ value
that is computed as ‘block
’,
‘table-cell
’ or ‘inline-block
’.
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 CSS Box Model 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: 3px 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 the SVG style basic shapes as defined by the SVG Shapes. When using the SVG syntax for defining shapes, all the lengths can be expressed in percentages resolved from the border box of the element. The (x,y) coordinates are relative to the element's border box. When defining shapes using percentages, the border box of the element must always be fully known in advance.
The following SVG shapes are supported by the CSS shapes module.
If the polygon is not closed the user-agent will automatically add a new vertex at the end.
Note, in case the polygon is not closed the user-agent will assume an additional vertex at the end.
Another way of defining
shapes is by specifying a source image whose alpha channel is used to
compute the outside-shape. When shapes are computed based on image, all
values of the ‘background-image
’
property can be applied.
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 also define cavities and inline flow content should wrap inside them. In order to avoid that, another exclusion element can be overlaid.
Shapes can be declared
using the ‘shape-outside
’, ‘shape-inside
’
or a combination for both properties. Using the ‘shape-outside
’
property changes the geometry of default shape used for exclusions, which
is the outter border box of the element. The outside shape has visual
effect when the element is exclusion (otherwise this property is ignored).
Using the ‘shape-inside
’ property, the content box of
an element is redefined and inline flow content wraps into that shape.
shape-outside
’
Property The ‘shape-outside
’
allows advance layout results such as inline flow content wrapping around
non-rectangular shapes. The property is used to modify the shape affecting
the surrounding inline flow from a rectangular border box to an arbitrary
geometry.
Name: | shape-outside |
---|---|
Value: | auto | <shape> | <image> |
Initial: | auto |
Applies to: | block-level elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | computed lengths for <shape>, the absolute URI for <image>, otherwise as specified |
The values of this property have the following meanings:
rectangle
’,‘
circle
’, ‘ellipse
’
or ‘polygon
’.
shape-inside
’
Property The ‘shape-inside
’
modifies the shape of the inner inline flow content from rectangular
content box to an arbitrary geometry.
When the property is set to
‘auto
’, the shape is taken from
the value of ‘shape-outside
’. In case both values of
‘shape-inside
’ and ‘shape-outside
’
are specified as ‘auto
’, the
content box of the element is used as the shape.
Name: | shape-inside |
---|---|
Value: | outside-shape | auto | <shape> | <image> |
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 <image>, otherwise as specified |
The values of this property have the following meanings:
shape-outside
’ property.
rectangle
’,‘
circle
’, ‘ellipse
’
or ‘polygon
’.
shape-image-threshold
’ Property The ‘shape-image-threshold
’ defines the alpha
channel threshold used to extract the shape using an image. The initial
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 <image> |
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:
shape
’
Shorthand PropertyName: | shape |
---|---|
Value: | <shape-outside> [ / <shape-inside> ] || <shape-image-threshold> |
Initial: | see individual properties |
Applies to: | block-level elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | see individual properties |
The ‘shape
’ property is a
shorthand property for setting the individual shape properties at the same
place in a style sheet.
Style declaration using the
‘shape
’
shorthand property
<style type="text/css">
.shape {
shape: rectangle(50px, 50px, 200px, 100px) / url("shape_image.png") 0.7;
}
</style>
The example above must be finished.
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.)
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
’,
3.3.4.
shape-image-threshold
’, 3.3.3.
<alphavalue>
’, 3.3.3.
shape-inside
’, 3.3.2.
shape-outside
’, 3.3.1.
wrap
’,
2.3.2.
wrap-flow
’, 2.1.1.
wrap-margin
’, 2.2.1.
wrap-padding
’, 2.2.2.
wrap-through
’, 2.3.1.
Property | Values | Initial | Applies to | Inh. | Percentages | Media |
---|---|---|---|---|---|---|
shape | <shape-outside> [ / <shape-inside> ] || <shape-image-threshold> | see individual properties | block-level elements | no | N/A | visual |
shape-image-threshold | <alphavalue> | 0.5 | block-level elements | no | alpha channel of the image specified by <image> | visual |
shape-inside | outside-shape | auto | <shape> | <image> | outside-shape | block-level elements | no | N/A | visual |
shape-outside | auto | <shape> | <image> | 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 | left | right | 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 |