CSS Exclusions and Shapes Module Level 3

Abstract

CSS Exclusions define arbitrary areas around which inline content ([CSS21]) content can flow. CSS Exclusions can be defined on any CSS block-level elements. CSS Exclusions extend the notion of content wrapping previously limited to floats.

CSS Shapes control the geometric shapes used for wrapping inline flow content outside or inside an element. CSS Shapes can be applied to any element. A circle shape on a float will cause inline content to wrap around the circle shape instead of the float's bounding box.

Combining CSS Exclusions and CSS Shapes allows sophisticated layouts, allowing interactions between shapes in complex positioning schemes.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than 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.

Changes since the previous draft are listed in the section “Change Log.”

Table of contents

• 1. Introduction
• 2. Definitions
• 3. Exclusions
  • 3.1. Declaring exclusions
    • 3.1.1. The ‘wrap-flow’ property
  • 3.2. Scope and effect of exclusions
    • 3.2.1. The ‘wrap-margin’ property
    • 3.2.2. The ‘wrap-padding’ Property
  • 3.3. Propagation of Exclusions
    • 3.3.1. The ‘wrap-through’ Property
    • 3.3.2. The ‘wrap’ Shorthand Property
  • 3.4. Exclusions order
  • 3.5. Processing model
    • 3.5.1. Description
    • 3.5.2. Step 1: resolve exclusion boxes belonging to each wrapping context
    • 3.5.3. Step 2: resolve wrapping contexts and layout containing blocks
    • 3.5.4. Step 2-A: resolve the position and size of exclusion boxes
    • 3.5.5. Step 2-B: layout containing block applying wrapping
    • 3.5.6. Example
      • 3.5.6.1. Step 1: resolve exclusion boxes belonging to each wrapping context
      • 3.5.6.2. Step 2: resolve wrapping contexts and layout containing blocks
        • 3.5.6.2.1. Resolving RWC-1
        • 3.5.6.2.2. Resolving RWC-2
  • 3.6. Floats and exclusions
    • 3.6.1. Similarities
    • 3.6.2. Differences
    • 3.6.3. Interoperability
      • 3.6.3.1. Effect of floats on exclusions
      • 3.6.3.2. Effect of exclusions on floats
• 4. Shapes
  • 4.1. Relation to the box model and float behavior
  • 4.2. Shapes from SVG Syntax
    • 4.2.1. Supported SVG Shapes
    • 4.2.2. Referencing SVG shapes
  • 4.3. Shapes from Image
  • 4.4. Declaring Shapes
    • 4.4.1. The ‘shape-outside’ Property
    • 4.4.2. The ‘shape-inside’ Property
    • 4.4.3. The ‘shape-image-threshold’ Property
• 5. Conformance
  • 5.1. Document Conventions
  • 5.2. Conformance Classes
  • 5.3. Partial Implementations
  • 5.4. Experimental Implementations
  • 5.5. Non-Experimental Implementations
  • 5.6. CR Exit Criteria
• Acknowledgments
• References
  • Normative references
  • Other references
• Index
• Property index
• Change Log
  • 5.7. Since December 13th 2011

1. Introduction

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.

2. Definitions

Exclusion box

A box ([CSS3BOX]) that defines an exclusion area for other boxes. The ‘wrap-flow’ property is used to make an element's generated box an exclusion box. An exclusion box contributes its exclusion area to its containing block's wrapping context. An element with a ‘float’ computed value other than ‘none’ does not become an exclusion.

Exclusion area

The area used for excluding inline flow content around an exclusion element. The exclusion area is equivalent to the border box. This specification's ‘shape-outside’ property can be used to define arbitrary, non-rectangular exclusion areas.

Float area

The area used for excluding inline flow content around a float element. By default, the float area is the float element's margin box. This specification's ‘shape-outside’ property can be used to define arbitrary, non-rectangular float areas.

Exclusion element

An block-level element which is not a float and generates an exclusion box. An element generates an exclusion box when its ‘wrap-flow’ property's computed value is not ‘auto’.

Wrapping context

The wrapping context of a box is a collection of exclusion areas contributed by its associated exclusion boxes. During layout, a box wraps its inline flow content in the area that corresponds to the subtraction of its wrapping context from its own content area.

A box 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 a box. 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.

3. Exclusions

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 wrap around 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 be used to change the shape of exclusion areas.

3.1. Declaring exclusions

An element becomes an exclusion when its ‘wrap-flow’ property has a computed value other than ‘auto’.

3.1.1. The ‘wrap-flow’ property

The values of this property have the following meanings:

auto

No exclusion is created. Inline flow content interacts with the element as usual. In particular, if the element is a float (see [CSS21]), the behavior is unchanged.

both

Inline flow content can flow on all sides of the exclusion.

start

Inline flow content can flow before the start edge of the exclusion area but must leave the area after the end edge of the exclusion empty.

end

Inline flow content can flow after the end edge of the exclusion area but must leave the area before the start edge of the exclusion empty.

maximum

Inline flow content can flow on the edge of the exclusion with the largest available space for the given line, and must leave the other edge of the exclusion empty.

clear

Inline flow content can only flow on top and bottom edges of the exclusion and must leave the areas before the start and after the end edges of the exclusion empty.

If the property's computed value is ‘auto’, the element does not become an exclusion.

Otherwise, a computed ‘wrap-flow’ property value of ‘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.

An exclusion element establishes a new block formatting context (see [CSS21]) for its content.

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 the element's inline content layout. All areas represented with a light or dark shade of gray are not available for inline content layout.

The ‘wrap-flow’ property values applied to an absolutely positioned element.

<div id="grid">
    <div id="exclusion">Donec metus …</div>
    <div id="content">Lorem ipsum…</div>
</div>

<style type="text/css"> 
#grid {
    width: 30em;
    height: 30em;
    display: grid;
    grid-columns: 50% 25% 25%;
    grid-rows: 40% 20% 40%;
}

#exclusion {
    grid-row: 2;
    grid-column: 2;
    wrap-flow: <see below>
}

#content {
    grid-row: 1;
    grid-row-span: 3;
    grid-column: 1;
    grid-column-span: 3;
}
</style> 

The following figures illustrate the visual rendering for different values of the ‘wrap-flow’ property. The gray grid lines are marking the grid cells. and the blue area is the exclusion box (positioned by the grid).

#exclusion{ wrap-flow: auto; }	#exclusion{ wrap-flow: both; }
#exclusion{ wrap-flow: start; }	#exclusion{ wrap-flow: end; }
#exclusion{ wrap-flow: maximum; }	#exclusion{ wrap-flow: clear; }

3.2. Scope and effect of exclusions

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 an element, the ‘wrap-through’ property can be used (see the propagation of exclusions section below).

For exclusions with ‘position:fixed’, the containing block is that of the root element.

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

3.2.2. The ‘wrap-padding’ Property

The ‘wrap-padding’ property can be used to offset 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.

3.3. Propagation of Exclusions

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.

3.3.1. The ‘wrap-through’ Property

The values of this property have the following meanings:

wrap

The element inherits its parent node's wrapping context. Its descendant inline content wraps around exclusions defined outside the element.

none

The element does not inherit its parent node's wrapping context. Its descendants are only subject to exclusion shapes defined inside the element.

Using the ‘wrap-through’ property to control the effect of exclusions.

<style type="text/css"> 
    #grid {
        display: grid;
        grid-columns: 25% 50% 25%;
        grid-rows: 25% 25% 25% 25%;
    }

    #exclusion {
        grid-row: 2;
        grid-row-span: 2;
        grid-column: 2;
        wrap-flow: <see below>
    }
    
    #rowA, #rowB {
        grid-row-span: 2;
        grid-column: 1;
        grid-column-span: 3;
    }

    #rowA {
        grid-row: 1;
    }
    
    #rowB {
        grid-row: 3;
    }
    </style>
        
<style type="text/css"> 
    .exclusion  {
    	wrap-flow: both; 
    	position: absolute; 
    	left: 20%;
    	top: 20%;
    	width: 50%;
    	height: 50%;
    	background-color: rgba(220, 230, 242, 0.5); 
    } 
</style> 

<div id="grid"> 
    <div class=”exclusion”></div> 
    <div id="rowA" style=”wrap-through: wrap;”> Lorem ipsum dolor sit amet...</div> 
    <div id="rowB" style=”wrap-through: none;”> Lorem ipsum dolor sit amet...</div> 
</div>

3.3.2. The ‘wrap’ Shorthand Property

The ‘wrap’ property is a shorthand property for setting the exclusions properties at the same place in the style sheet.

3.4. Exclusions order

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. The ‘z-index’ property can be used to change the ordering of positioned exclusion boxes (see [CSS21]). Statically positioned exclusions are not affected by the ‘z-index’ property and 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; }

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.

3.5. Processing model

3.5.1. Description

Applying exclusions is a two-step process:

• Step 1: resolve exclusion boxes belonging to each wrapping context
• Step 2: resolve wrapping contexts and layout each containing block in turn:
  • Step 2-A: resolve the position and size of exclusion boxes
  • Step 2-B: layout containing block, wrapping around exclusion areas

3.5.2. Step 1: resolve exclusion boxes belonging to each wrapping context

In this step, the user agent determines which containing block each exclusion area belongs to. This is a simple step, based on the definition of containing blocks and elements with a computed value for ‘wrap-flow’ that is not auto.

3.5.3. Step 2: resolve wrapping contexts and layout containing blocks

In this step, starting from the top of the rendering tree (see [CSS21]), the the agent processes each containing block in two sub-steps.

3.5.4. Step 2-A: resolve the position and size of exclusion boxes

Resolving the position and size of exclusion boxes in the wrapping context may or may not require a layout. For example, if an exclusion box is absolutely positioned and sized, a layout may not be needed to resolve its position and size. In other situations, laying out the containing block's content is required.

When a layout is required, it is carried out without applying any exclusion area. In other words, the containing block is laid out without a wrapping context.

Step 2-A yields a position and size for all exclusion boxes in the wrapping context.

Scrolling is ignored in this step when resolving the position and size of ‘position:fixed’ exclusion boxes.

3.5.5. Step 2-B: layout containing block applying wrapping

Finally, the content of the containing block is laid out, with the inline content wrapping around the wrapping content‘s exclusion areas (which may be different from the exclusion box because of the ’shape-outside' property).

When the containing block itself is an exclusion box, then rules on exclusions order define which exclusions affect the inline and descendant content of the box.

3.5.6. Example

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

<html>
<style>
#d1 {
    position:relative;
    height: auto;
    color: #46A4E9;
    border: 1px solid gray;
}

#e1 {
    -webkit-wrap-flow: both;
    position: absolute; 
    left: 50%; 
    top: 50%; 
    width: 40%; 
    height: 40%; 
    border: 1px solid red;
    margin-left: -20%;
    margin-top: -20%;
}

#d2 {
    position: static;
    width: 100%;
    height: auto;
    color: #808080;
}

#e2 {
    -webkit-wrap-flow: both;
    position: absolute; 
    right: 5ex; 
    top: 1em; 
    width: 12ex;
    height: 10em; 
    border: 1px solid lime;
}
</style>
<body>
    <div id="d1">
        Lorem ipsusm ...
        <p id="e1"></p>
    </div>
    <div id="d2">
        Lorem ipsusm ...
        <p id="e2" ></p>
    </div>
</body>
</html>

The following figures illustrate:

• the document's DOM tree
• the layout tree of generated block boxes

DOM tree

Layout tree of generated block boxes

3.5.6.1. Step 1: resolve exclusion boxes belonging to each wrapping context

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 box generated by e1 is positioned in its containing block's box, which is the d1-box, 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 boxes belonging to the wrapping contexts of all the elements can be determined:

• The wrapping context for the html element contains the e2 box: WC-1 (Wrapping Context 1)
• The wrapping context for the body element inherits the html element's wrapping context: WC-1
• The wrapping context for d1 inherits the body element's wrapping context and adds the e1-box to it. So the wrapping context is made of both the e1-box and the e2-box: WC-2
• The wrapping context for d2 inherits the body element's wrapping context: WC-1

3.5.6.2. Step 2: resolve wrapping contexts and layout containing blocks

In this step, each containing block is processed in turn. For each containing block, we (conceptually) go through two phases:

1. resolve the wrapping context: resolve the position and size of its exclusions
2. layout the containing block

In our example, this breaks down to:

1. resolve the position and size of the exclusions belonging to WC-1: RWC-1 (Resolved Wrapping Context 1).
2. layout the initial containing block (i.e., layout its content):
   1. resolve the html element's wrapping context: RWC-1
   2. layout the html element:
      1. resolve the body element's wrapping context: RWC-1
      2. layout the body element:
         1. resolve the d1 element's wrapping context: RWC-2
         2. layout the d1 element
         3. resolve the d2 element's wrapping context: RWC-1
         4. layout the d2 element

3.5.6.2.1. Resolving RWC-1

The top-most wrapping context in the layout tree contains the e2 exclusion. Its position and size needs to be resolved. In general, computing an exclusion's position and size may or may not require laying out other content. In our example, no content needs to be laid out to resolve the e2 exclusion's position because it is absolutely positioned and its size can be resolved without layout either. At this point, RWC-1 is resolved and can be used when laying inline content out.

3.5.6.2.2. Resolving RWC-2

The process is similar: the position of the e1 exclusion needs to be resolved. Again, resolving the exclusion's position and size may require processing the containing block (d1 here). It is the case here because the size and position of e1 depend on resolving the percentage lengths. The percentages are relative to the size of d1‘s box. As a result, in order to resolve a size for d1’s box, a first layout of d1 is done without any wrapping context (i.e., no exclusions applied). The layout yields a position and size for e1‘s box.

At this point, RWC-2 is resolved because the position and size of both e1 and e2 are resolved.

The important aspect of the above processing example is that once an element’s wrapping context is resolved (by resolving its exclusions' position and size), the position and size of the exclusions are not re-processed if the element's size changes between the layout that may be done without considering any wrapping context (as for RWC-2) and the layout done with the resolved wrapping context. This is what breaks the possible circular dependency between the resolution of wrapping contexts and the layout of containing blocks.

3.6. Floats and exclusions

3.6.1. Similarities

There are similarities between floats an exclusions in that inline content wraps around floats and also wraps around exclusion areas. However, there are very significant differences.

3.6.2. Differences

• scope. While floats apply to content that follows in the document, exclusions apply to content in their containing block.
• positioning. Floats are part of the inline flow and ‘float’ on the line box. Authors can control how the floats move on the line box, to the right or to the left. By contrast, exclusions can be positioned using any positioning scheme such as grid layout ([CSS3-GRID-LAYOUT]), flexible box ([CSS3-FLEXBOX]) or any other CSS positioning scheme.
• separation of concerns. Making an element a float determines both its positioning scheme and its effect on inline content. Making an element an exclusion only determines its impact on inline content and does not impose constraints on its positioning method.

3.6.3. Interoperability

3.6.3.1. Effect of floats on exclusions

Floats have an effect on the positioning of exclusions and the layout of their inline content. For example, if an exclusion is an inline-box which happens to be on the same line as a float, its' position, as computed in Step 2-A will be impacted by the float, as is any other inline content.

3.6.3.2. Effect of exclusions on floats

Exclusions have an effect on the positioning of floats as they have an effect on inline content. Therefore, in Step 2-B, floats will avoid exclusion areas.

4. Shapes

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 or the float area for a float. The inside shape defines an element's content shape and the element's inline content will flow within that shape.

It is important to note that while outside shapes only apply to exclusions and floats, inside shapes apply to all block-level elements.

4.1. Relation to the box model and float behavior

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 [CSS3BOX] module.

However, floats are an exception. If a float has an outside shape, its positioning is resolved as defined in [CSS21] but using the outside shape's bounding box is used in lieu of the float's margin box.

CSS ‘shape-outside’ and CSS box model relation: the red box illustrates the exclusion element's content box, which is unmodified and subject to normal CSS positioning (here absolute positioning).

<style type="text/css"> 
    .exclusion  {
    	wrap-flow: both; 
    	position: absolute; 
    	top: 25%;
    	left: 25%;
    	width: 50%;
    	height: 50%;
    	shape-outside: circle(50%, 50%, 50%); 
    	border: 1px solid red; 
    } 
</style> 

<div style=”position: relative;”> 
    <div class=”exclusion”></div> 
    Lorem ipsum dolor sit amet... 
</div>

In the following example the left and right floating div elements specify a triangular shape using the ‘shape-outside’ property.

<div style="text-align:center;">
      <div id="float-left"></div>
      <div id="float-right"></div>
      <div>
      Sometimes a web page's text content appears to be
      funneling your attention towards a spot on the page
      to drive you to follow a particular link.  Sometimes
      you don't notice.
      </div>
</div>

<style type="text/css">
#float-left {
      shape-outside: polygon(0,0 100%,100% 0,100%);
      float: left;
      width: 40%;
      height: 12ex;
  }

#float-right {
      shape-outside: polygon(100%,0 100%,100% 0,100%);
      float: right;
      width: 40%;
      height: 12ex;
  }
  </style>
</div>

4.2. Shapes from SVG Syntax

Shapes can be specified using SVG basic shapes. The definitions use <length> type and the <percentage> types (see [CSS3VAL]). Percentages are resolved from the border box of the element to which the property applies. For the radius r of the circle shape, a percentage value is resolved as specified in the SVG recommendation (see [SVG11])

4.2.1. Supported SVG Shapes

The following SVG shapes are supported by the CSS shapes module.

rectangle([<length>|<percentage>]{4} [ curve [<length>|<percentage>]{1,2} ]? )

• The four values represent x, y, width and height - define the bounding box of the rectangle
• The two ‘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

circle([<length>|<percentage>]{3})

• The three values values represent cx, cy, r - The x and y axis coordinate of the center of the circle and the radius of the circle

ellipse([<length>|<percentage>]{4})

• The four values represent cx, cy, rx and ry - The x and y coordinate of the center of the ellipse and the x and y axis radius of the ellipse

polygon([<fill-rule>,]? [<length>|<percentage>]{2}#)

• fillRule - The filling rule used to determine the interior of the polygon. See fill-rule property in SVG for details. Possible values are nonzero or evenodd. Default value when omitted is nonzero.
• The two length values represent xi and yi - the x and y axis coordinates of the i-th vertex of the polygon.

If the polygon is not closed the user-agent will automatically add a new vertex at the end.

4.2.2. Referencing SVG shapes

An SVG shape can be referenced using the url() syntax. The shape can be any of the SVG basic shapes or a path 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%" 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 corner 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 resolve to 0.

4.3. Shapes from Image

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.

For animated raster image formats (such as GIF), the first frame of the animation sequence is used. For SVG images ([SVG11]), the image is rendered without animations applied.

4.4. Declaring Shapes

Shapes are declared with the ‘shape-outside’ or ‘shape-inside’ properties. The ‘shape-outside’ property changes the geometry of an exclusion element‘s exclusion area or or a float element’s float area. If the element is not an exclusion element (see the ‘wrap-flow’ property) or a float, 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. The ‘shape-inside’ property applies to all block-level elements.

4.4.1. The ‘shape-outside’ Property

The values of this property have the following meanings:

auto

The shape is computed based on the border box of the element.

<shape>

The shape is computed based on the values of one of ‘rectangle’, ‘circle’, ‘ellipse’ or ‘polygon’.

<uri>

If the <uri> references an SVG shape element, that element defines the shape. Otherwise, if the <uri> references an image, the shape is extracted and computed based on the alpha channel of the specified image. If the <uri> does not reference an SVG shape element or an image, the effect is as if the value ‘auto’ had been specified.

Arbitrary shapes for exclusions

4.4.2. The ‘shape-inside’ Property

The ‘shape-inside’ modifies the shape of the inner inline flow content from rectangular content box to an arbitrary geometry.

The values of this property have the following meanings:

outside-shape

The shape is computed based on the computed value of the ‘shape-outside’ property.

auto

The shape is computed based on the content box of the element.

<shape>

The shape is computed based on the values of one of ‘rectangle’,‘ circle’, ‘ellipse’ or ‘polygon’.

<uri>

If the <uri> references an SVG shape element, that element defines the shape. Otherwise, if the <uri> references an image, the shape is extracted and computed based on the alpha channel of the specified image. If the <uri> does not reference an SVG shape element or an image, the effect is as if the value ‘auto’ had been specified.

The ‘shape-inside’ property applies to floats.

The ‘shape-inside’ property may not apply on some elements such as elements with a computed ‘display’ value of ‘table’.

4.4.3. The ‘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’.

The values of this property have the following meanings:

<alphavalue>

A <number> value used to set the threshold used for extracting a shape from an image. Any values outside the range 0.0 (fully transparent) to 1.0 (fully opaque) will be clamped to this range.

The shape properties apply to

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:

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 Exclusions and Shapes is defined for three conformance classes:

style sheet

A CSS style sheet.

renderer

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

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:

independent

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.

interoperable

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.

implementation

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.

Acknowledgments

This specification is made possible by input from Andrei Bucur, Alexandru Chiculita, Arron Eicholz, Daniel Glazman, Arno Gourdol, Chris Jones, Marcus Mielke, Alex Mogilevsky, Mihnea Ovidenie, Virgil Palanciuc, Peter Sorotokin, Eugene Veselov, Stephen Zilles and the CSS Working Group members.

References

Normative references

[CSS21]

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

[CSS3BOX]

Bert Bos. CSS basic box model. 9 August 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-css3-box-20070809

[CSS3VAL]

Håkon Wium Lie; Tab Atkins; Elika J. Etemad. CSS Values and Units Module Level 3. 8 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-css3-values-20120308/

[RFC2119]

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

[SVG11]

Erik Dahlström; et al. Scalable Vector Graphics (SVG) 1.1 (Second Edition). 16 August 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-SVG11-20110816/

Other references

[CSS3-FLEXBOX]

Tab Atkins Jr.; Alex Mogilevsky; L. David Baron. CSS Flexible Box Layout Module. 29 November 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-css3-flexbox-20111129/

[CSS3-GRID-LAYOUT]

Alex Mogilevsky; et al. Grid Layout. 7 April 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-css3-grid-layout-20110407

Index

• authoring tool, 5.2.
• Content area, 2.
• Exclusion area, 2.
• Exclusion box, 2.
• Exclusion element, 2.
• Float area, 2.
• outside-inside, 2.
• renderer, 5.2.
• ‘shape-image-threshold’, 4.4.3.
  • ‘<alphavalue>’, 4.4.3.
• ‘shape-inside’, 4.4.2.
  • ‘auto’, 4.4.2.
  • ‘outside-shape’, 4.4.2.
  • ‘<shape>’, 4.4.2.
  • ‘<uri>’, 4.4.2.
• ‘shape-outside’, 4.4.1.
  • ‘auto’, 4.4.1.
  • ‘<shape>’, 4.4.1.
  • ‘<uri>’, 4.4.1.
• style sheet
  • as conformance class, 5.2.
• ‘wrap’, 3.3.2.
• ‘wrap-flow’, 3.1.1.
  • ‘auto’, 3.1.1.
  • ‘both’, 3.1.1.
  • ‘clear’, 3.1.1.
  • ‘end’, 3.1.1.
  • ‘maximum’, 3.1.1.
  • ‘start’, 3.1.1.
• ‘wrap-margin’, 3.2.1.
• ‘wrap-padding’, 3.2.2.
• Wrapping context, 2.
• ‘wrap-through’, 3.3.1.
  • ‘none’, 3.3.1.
  • ‘wrap’, 3.3.1.

Property index

Change Log

5.7. Since December 13th 2011

• Clarified processing model
• Clarified interaction with floats
• Clarified that an exclusion element establishes a new block formatting context