css3-flexbox/Overview.src.html

Sun, 11 Mar 2012 21:15:40 -0700

author
Alex Mogilevsky <alexmog@microsoft.com>
date
Sun, 11 Mar 2012 21:15:40 -0700
changeset 4726
53deb8301b61
parent 4725
d3362b8a88c8
child 4728
5ff50322db2c
permissions
-rw-r--r--

replace "flex item" with "flexbox item"

alexmog@4725 1 <!DOCTYPE html>
alexmog@4725 2 <html lang="en">
alexmog@4725 3 <head>
alexmog@4725 4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
alexmog@4725 5 <title>CSS Flexible Box Layout Module</title>
alexmog@4725 6 <link rel="stylesheet" type="text/css" href="http://dev.w3.org/csswg/default.css">
alexmog@4725 7 <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED">
alexmog@4724 8 <style>
alexmog@4724 9 code.one-line { white-space: pre; }
alexmog@4724 10 .code-and-figure {
alexmog@4724 11 display: table;
alexmog@4724 12 margin: 0 auto;
alexmog@4724 13 border-spacing: 1em;
alexmog@4724 14 }
alexmog@4724 15 .code-and-figure > div {
alexmog@4724 16 display: table-cell;
alexmog@4724 17 vertical-align: middle;
alexmog@4724 18 }
alexmog@4725 19 </style>
alexmog@4725 20 </head><body>
alexmog@4725 21
alexmog@4725 22 <div class="head">
alexmog@4725 23 <!--logo-->
alexmog@4725 24
alexmog@4725 25 <h1 id="head-box-flexible">CSS Flexible Box Layout Module</h1>
alexmog@4725 26 <h2 class="no-num no-toc" id="w3c-working">[LONGSTATUS], [DATE]</h2>
alexmog@4725 27
alexmog@4725 28 <dl>
alexmog@4725 29 <dt>This version:
alexmog@4725 30 <!--<dd><a href="[VERSION]">[VERSION]</a>-->
alexmog@4725 31 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
alexmog@4725 32
alexmog@4725 33 <dt>Latest version:
alexmog@4725 34 <!--<dd><a href="[LATEST]">[LATEST]</a>-->
alexmog@4725 35 <dd><a href="http://www.w3.org/TR/css3-flexbox/">http://www.w3.org/TR/css3-flexbox/</a>
alexmog@4725 36
alexmog@4725 37 <dt>Editor's Draft:
alexmog@4725 38 <dd><a href="http://dev.w3.org/csswg/css3-flexbox/">http://dev.w3.org/csswg/css3-flexbox/</a>
alexmog@4725 39
alexmog@4725 40 <dt>Previous versions:
alexmog@4725 41 <dd><a href="http://www.w3.org/TR/2011/WD-css3-flexbox-20111129/">http://www.w3.org/TR/2011/WD-css3-flexbox-20111129/</a>
alexmog@4725 42 <dd><a href="http://www.w3.org/TR/2011/WD-css3-flexbox-20110322/">http://www.w3.org/TR/2011/WD-css3-flexbox-20110322/</a>
alexmog@4725 43 <dd><a href="http://www.w3.org/TR/2009/WD-css3-flexbox-20090723/">http://www.w3.org/TR/2009/WD-css3-flexbox-20090723/</a>
alexmog@4725 44
alexmog@4725 45 <dt>Issues List:</dt>
alexmog@4725 46 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=CSS&component=Flexbox&resolution=---">Bugzilla Bugs for Flexbox</a></dd>
alexmog@4725 47
alexmog@4725 48 <dt>Discussion:</dt>
alexmog@4725 49 <dd><a href="http://lists.w3.org/Archives/Public/www-style/">www-style@w3.org</a> with subject line "<code>[css3-flexbox] …message topic…</code>"
alexmog@4725 50
alexmog@4725 51 <dt>Editors:
alexmog@4725 52 <dd><a href="http://www.xanthir.com/contact">Tab Atkins Jr.</a>, Google Inc.</dd>
alexmog@4725 53 <dd>Alex Mogilevsky, Microsoft Corporation, <a href="mailto:alexmog@microsoft.com">alexmog@microsoft.com</a>
alexmog@4725 54 <dd>L. David Baron, Mozilla Corporation, <a href="mailto:dbaron@dbaron.org">dbaron@dbaron.org</a>
alexmog@4725 55
alexmog@4725 56 <dt>Authors and former editors:
alexmog@4725 57 <dd>Neil Deakin, Mozilla Corporation, <a href="mailto:enndeakin@gmail.com">enndeakin@gmail.com</a>
alexmog@4725 58 <dd>Ian Hickson, formerly of Opera Software, <a href="mailto:ian@hixie.ch">ian@hixie.ch</a>
alexmog@4725 59 <dd>David Hyatt, formerly of Netscape Corporation, <a href="mailto:hyatt@apple.com">hyatt@apple.com</a>
alexmog@4725 60 </dl>
alexmog@4725 61 <!--copyright-->
alexmog@4725 62
alexmog@4725 63 <hr title="Separator for header">
alexmog@4725 64 </div>
alexmog@4725 65
alexmog@4725 66 <h2 class="no-num no-toc" id="abstract">
alexmog@4725 67 Abstract</h2>
alexmog@4725 68
alexmog@4725 69 <p>The specification describes a CSS box model optimized for user interface design. In the flexbox layout model, the children of a flexbox can be laid out in any direction, and can "flex" their sizes, either growing to fill unused space or shrinking to avoid overflowing the parent. Both horizontal and vertical alignment of the children can be easily manipulated. Nesting of these boxes (horizontal inside vertical, or vertical inside horizontal) can be used to build layouts in two dimensions.</p>
alexmog@4725 70
alexmog@4725 71 <h2 class="no-num no-toc" id="status">Status of this document</h2>
alexmog@4725 72 <!--status-->
alexmog@4725 73
alexmog@4725 74 <h2 class="no-num no-toc" id="table">Table of contents</h2>
alexmog@4725 75 <!--toc-->
alexmog@4725 76
alexmog@4725 77
alexmog@4725 78 <h2 id="intro">
alexmog@4725 79 Introduction</h2>
alexmog@4725 80
alexmog@4725 81 <p><em>This section is not normative.</em>
alexmog@4725 82
alexmog@4725 83 <p>CSS 2.1 defined four layout modes &mdash; algorithms which determine the size and position of boxes based on their relationships with their sibling and ancestor boxes: block layout, designed for laying out documents; inline layout, designed for laying out text; table layout, designed for laying out information in a tabular format; and positioned layout, designed for very explicit positioning without much regard for other elements in the document. This module introduces a new layout mode, flexbox layout, which is designed for laying out more complex applications and webpages.</p>
alexmog@4725 84
alexmog@4725 85 <p>Flexbox layout is superficially similar to block layout. It lacks many of the more complex text or document-formatting properties that can be used in block layout, such as 'float' and 'columns', but in return it gains more simple and powerful tools for aligning its contents in ways that webapps and complex web pages often need. </p>
alexmog@4725 86
alexmog@4725 87 <p>The contents of a flexbox can be laid out in any direction (left, right, down, or even up!), can have their order swapped around dynamically (i.e., display order is independent of source order), and can "flex" their sizes and positions to respond to the available space. If a flexbox is <i>multi-line</i>, the flexbox items flow in two dimensions, wrapping into separate lines in a fashion similar to how text is wrapped into multiple lines.</p>
alexmog@4725 88
alexmog@4725 89 <div class="example">
alexmog@4725 90 <p>For example, the following HTML snippet uses flexbox to create a toolbar with icons. The flexbox is horizontal, and the children's widths don't fill the flexbox's width, so the additional space is distributed around and between the children. As the flexbox grows (perhaps because the user is viewing the page on a wider screen), the children spread out evenly and automatically:</p>
alexmog@4725 91
alexmog@4725 92 <pre>
alexmog@4725 93 &lt;ul>
alexmog@4725 94 &lt;li>&lt;button>&lt;img src='new.svg' alt="New">&lt;/button>&lt;/li>
alexmog@4725 95 &lt;li>&lt;button>&lt;img src='upload.svg' alt="Upload">&lt;/button>&lt;/li>
alexmog@4725 96 &lt;li>&lt;button>&lt;img src='save.svg' alt="Save">&lt;/button>&lt;/li>
alexmog@4725 97 &lt;li>&lt;button>&lt;img src='trash.svg' alt="trash">&lt;/button>&lt;/li>
alexmog@4725 98 &lt;/ul>
alexmog@4725 99 &lt;style>
alexmog@4725 100 ul { display: flexbox; flex-pack: distribute; }
alexmog@4725 101 /* Irrelevant styling for this example removed. */
alexmog@4725 102 &lt;/style></pre>
alexmog@4725 103
alexmog@4725 104 <div class='figure'>
alexmog@4725 105 <img src="images/toolbar-example.svg" width=400 height=140>
alexmog@4725 106 <p class='caption'>Example rendering of the above code snippet, at two different flexbox widths.</p>
alexmog@4725 107 </div>
alexmog@4725 108 </div>
alexmog@4725 109
alexmog@4725 110 <h3 id="placement">
alexmog@4725 111 Module interactions</h3>
alexmog@4725 112
alexmog@4725 113 <p>This module extends the definition of the 'display' property.
alexmog@4725 114
alexmog@4725 115 <h3 id="values">
alexmog@4725 116 Values</h3>
alexmog@4725 117
alexmog@4725 118 <p>This specification follows the <a href="http://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> 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 &lt;color&gt; value type as used in this specification.</p>
alexmog@4725 119
alexmog@4725 120 <p>In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the <a href="http://www.w3.org/TR/CSS21/cascade.html#value-def-inherit">''inherit''</a> keyword as their property value. For readability it has not been repeated explicitly.
alexmog@4725 121
alexmog@4725 122 <h2 id='box-model'>
alexmog@4725 123 The Flexbox Box Model</h2>
alexmog@4725 124
alexmog@4725 125 <p>An element with ''display:flexbox'' or ''display:inline-flexbox'' is a <dfn>flexbox</dfn>. Children of a flexbox are called <dfn title="flexbox item|flexbox items|flexbox item's" id="flexbox-item">flexbox items</dfn> and are laid out using the flexbox box model.</p>
alexmog@4725 126
alexmog@4725 127 <p>Unlike block layout, which is normally biased towards laying things out vertically, and inline layout, which is normally biased toward laying things out horizontally, the flexbox layout algorithm is agnostic as to the direction the flexbox happens to be laid out in. To make it easier to talk about flexbox layout in a general way, we will define several direction-agnostic terms here to make the rest of the spec easier to read and understand.</p>
alexmog@4725 128
alexmog@4725 129 <div class='figure'>
alexmog@4725 130 <img src='images/flex-direction-terms.svg' width=510 height=300>
alexmog@4725 131 <p class='caption'>An illustration of the various directions and sizing terms used in this specification, respectively for ''row'' and ''column'' flexboxes.</p>
alexmog@4725 132 </div>
alexmog@4725 133
alexmog@4725 134 <p>The <dfn>main axis</dfn> of a flexbox is the axis on which <i>flexbox items</i> are laid out along. The <i>flexbox items</i> are ordered such that they start on the <dfn>main-start</dfn> side of the flexbox, and go toward the <dfn>main-end</dfn> side. A <i>flexbox item's</i> width or height, whichever is in the <i>main axis</i>, is the item's <dfn>main size</dfn>. The <i>flexbox item's</i> <dfn>main size property</dfn> is either the 'width' or 'height' property, whichever is in the <i>main axis</i>.</p>
alexmog@4725 135
alexmog@4725 136 <p>The axis perpendicular to the <i>main axis</i> is called the <dfn>cross axis</dfn>, and similarly has <dfn>cross-start</dfn> and <dfn>cross-end</dfn> directions and sides defined. The width or height of a <i>flexbox item</i>, whichever is in the <i>cross axis</i>, is the item's <dfn>cross size</dfn>, and similarly the <dfn>cross size property</dfn> is whichever of 'width' or 'height' that is in the <i>cross axis</i>.</p>
alexmog@4725 137
alexmog@4725 138 <p>The contents of a flexbox can be easily and powerfully manipulated with a handful of properties. Most significantly, <i>flexbox items</i> can "flex" their <i>main size</i> by using the 'flex' property. This "flexing" allows the items to get bigger or smaller based on the available space in the page. If there is leftover space in the flexbox after all of the <i>flexbox items</i> have finished flexing, the items can be aligned, centered, or distributed with the 'flex-pack' property. <i>Flexbox items</i> can also be completely rearranged within the flexbox with the 'flex-order' property.</p>
alexmog@4725 139
alexmog@4725 140 <p>In the <i>cross axis</i>, <i>flexbox items</i> can either "flex" to fill the available space or be aligned within the space with the 'flex-align' property. If a flexbox is <i>multi-line</i>, new lines are added in the <i>cross-end</i> direction, and can similarly be aligned, centered, or distributed within the flexbox with the 'flex-line-pack' property.</p>
alexmog@4725 141
alexmog@4725 142
alexmog@4725 143 <h2 id='display-flexbox'>
alexmog@4725 144 New values for 'display' property</h2>
alexmog@4725 145
alexmog@4725 146 <table class="propdef">
alexmog@4725 147 <tr>
alexmog@4725 148 <th>Name:
alexmog@4725 149 <td>display
alexmog@4725 150 <tr>
alexmog@4725 151 <th><a href="http://dev.w3.org/csswg/css-module/#values">New value</a>:
alexmog@4725 152 <td>flexbox | inline-flexbox
alexmog@4725 153 </table>
alexmog@4725 154
alexmog@4725 155 <p>You can declare that an element is a flexbox, and thus should use flexbox layout for its contents, by setting the 'display' property on the element to the value 'flexbox' or 'inline-flexbox'.</p>
alexmog@4725 156
alexmog@4725 157 <p>The ''flexbox'' value makes the flexbox a block-level element. The ''inline-flexbox'' value makes the flexbox an inline-level element. When it is necessary to distinguish them, this specification will refer to the former kind of flexbox as a <dfn id="block-flexbox" title="block flexbox|block flexboxes">block flexbox</dfn> and the latter type as an <dfn id="inline-flexbox" title="inline flexbox|inline flexboxes">inline flexbox</dfn>.</p>
alexmog@4725 158
alexmog@4725 159 <p>Flexboxes use a new layout algorithm, and so some properties that were designed with the assumption of block layout don't make sense in a flexbox context. In particular:</p>
alexmog@4725 160
alexmog@4725 161 <ul>
alexmog@4725 162 <li>all of the 'column-*' properties in the Multicol module have no effect on a flexbox.</li>
alexmog@4725 163
alexmog@4725 164 <li>'float' and 'clear' have no effect on a flexbox item. Using 'float' on an element still causes that element's 'display' property to compute to ''block'', as normal, because that occurs before flexbox items are determined (the algorithm for wrapping children of a flexbox into <i>flexbox items</i> needs the computed value of 'display').</li>
alexmog@4725 165
alexmog@4725 166 <li>'vertical-align' has no effect on the alignment of a flexbox item in the flexbox</li>
alexmog@4725 167 </ul>
alexmog@4725 168
alexmog@4725 169 <p>If an element's specified value for 'display' is ''inline-flexbox'' and the element is floated or absolutely positioned, the computed value of 'display' must be ''flexbox''.</p>
alexmog@4725 170
alexmog@4725 171 <p>A flexbox establishes a new <dfn>flexbox formatting context</dfn> for its contents. This is similar to a block formatting context root: floats do not intrude into the flexbox, and the flexbox's margins do not collapse with the margins of its contents. Additionally, each of the <i>flexbox items</i> establish a new formatting context for its contents.</p>
alexmog@4725 172
alexmog@4725 173 <h2 id='flex-items'>
alexmog@4725 174 Flexbox Items</h2>
alexmog@4725 175
alexmog@4725 176 <p>Flexbox layout algorithm operates on <i>flexbox items</i>, which are boxes that satisfy at least one of the following criteria:</p>
alexmog@4725 177
alexmog@4725 178 <ol>
alexmog@4725 179 <li>Immediate block-level children of flexbox</li>
alexmog@4725 180
alexmog@4725 181 <li>Atomic inline-level children of flexbox</li>
alexmog@4725 182
alexmog@4725 183 <li>Contiguous run of non-replaced inline children, wrapped into an anonymous box</li>
alexmog@4725 184 </ol>
alexmog@4725 185
alexmog@4725 186 <p>Some values of 'display' trigger "fixup" to ensure a sensible tree structure. For example, a lone ''table-cell'' box is fixed up by generating ''table'', ''table-row-group'', and ''table-row'' boxes around it. This fixup must occur <em>before</em> a flexbox's contents are checked to see if it's necessary to generate anonymous flexbox items.</p>
alexmog@4725 187
alexmog@4725 188 <p class='note'>In the future, other kinds of fixup such as ''display:run-in'' or ''display:ruby'' should also run before flexbox fixup.</p>
alexmog@4725 189
alexmog@4725 190 <div class="example">
alexmog@4725 191 <p>Examples of flexbox items:</p>
alexmog@4725 192 <pre>
alexmog@4725 193 &lt;div style="display:flexbox">
alexmog@4725 194
alexmog@4725 195 &lt;!-- flexbox item: block-level child -->
alexmog@4725 196 &lt;div id="item1">block&lt;/div>
alexmog@4725 197
alexmog@4725 198 &lt;!-- not a flexbox item, because it's out-of-flow -->
alexmog@4725 199 &lt;div id="not-an-item1.5" style="position: absolute;">block&lt;/div>
alexmog@4725 200
alexmog@4725 201 &lt;!-- flexbox item: block-level child -->
alexmog@4725 202 &lt;div id="item2" style="display:table">table&lt;/div>
alexmog@4725 203
alexmog@4725 204 &lt;!-- flexbox item: anonymous table wrapped around table-cell -->
alexmog@4725 205 &lt;div id="item3" style="display:table-cell">table-cell&lt;/div>
alexmog@4725 206
alexmog@4725 207 &lt;!-- flexbox item: anonymous block around inline content -->
alexmog@4725 208 anonymous item 4
alexmog@4725 209
alexmog@4725 210 &lt;!-- flexbox item: block-level child -->
alexmog@4725 211 &lt;div id="item5">block&lt;/div>
alexmog@4725 212
alexmog@4725 213 &lt;!-- flexbox item: anonymous block around inline content -->
alexmog@4725 214 anonymous item 6.1
alexmog@4725 215 &lt;span id="item6.1">
alexmog@4725 216 text 6.2
alexmog@4725 217 &lt;div id="not-an-item6.3">block&lt;/div>
alexmog@4725 218 text 6.4
alexmog@4725 219 &lt;/span>
alexmog@4725 220
alexmog@4725 221 &lt;!-- flexbox item: block-level replaced element -->
alexmog@4725 222 &lt;iframe id="item7"></iframe>
alexmog@4725 223
alexmog@4725 224 &lt;!-- flexbox item: inline-level replaced element -->
alexmog@4725 225 &lt;img id="item7" style="display:inline">
alexmog@4725 226
alexmog@4725 227 &lt;!-- flexbox item: inline-level replaced element -->
alexmog@4725 228 &lt;button id="item8">button&lt;/button>
alexmog@4725 229
alexmog@4725 230 &lt;!-- flexbox item: inline-table -->
alexmog@4725 231 &lt;div id="item9" style="display:inline-table">table&lt;/div>
alexmog@4725 232
alexmog@4725 233 &lt;!-- flexbox item: floated inline, which changes to a block -->
alexmog@4725 234 &lt;span id="item10" style="float: left;">span&lt;/span>
alexmog@4725 235 &lt;/div></pre>
alexmog@4725 236
alexmog@4726 237 <p>Notice that block element "not-an-item6.3" is not a separate flexbox item, because it is contained inside an inline element which is being wrapped into an anonymous
alexmog@4726 238 flexbox item. Similarly, the block element "not-an-item1.5" is not a flexbox item, because it's absolutely positioned and thus out of flow.</p>
alexmog@4725 239 </div>
alexmog@4725 240
alexmog@4725 241 <h3 id='abspos-flexbox-items'>
alexmog@4725 242 Absolutely Positioned Flexbox Children</h3>
alexmog@4725 243
alexmog@4725 244 <p>Absolutely positioned children of a flexbox are not <i>flexbox items</i>, but they leave behind "placeholders" in their normal position in the box tree. These placeholders are anonymous inline boxes with a width and height of ''0px'', and they interact normally with the flexbox layout algorithm. In particular, they'll trigger the creation an anonymous flexbox item wrapper boxes, or join neighboring inline elements in <em>their</em> anonymous flexbox item wrapper boxes.</p>
alexmog@4725 245
alexmog@4725 246 <p>The "static position" of an absolutely positioned child of a flexbox (the position when the 'top'/'right'/'bottom'/'left' properties are ''auto''), then, is the final position of their corresponding placeholder, after flexbox layout has been performed.</p>
alexmog@4725 247
alexmog@4725 248 <p class='note'>Note: In most cases, this means that absolutely positioned items will have no effect on flexbox layout, even if they force the generation of an anonymous flexbox item wrapper, because those wrapper items will also collapse to zero size and have no effect. The only exception is when the flexbox has ''flex-pack:justify'', in which case the anonymous flexbox item will cause there to be two packing spaces where there would otherwise be only one, which will appear as a double-size space between two "real" items.</p>
alexmog@4725 249
alexmog@4725 250
alexmog@4725 251 <h2 id='multi-line'>
alexmog@4725 252 Multi-line Flexbox</h2>
alexmog@4725 253
alexmog@4725 254 <p>A flexbox can be either <i>single-line</i> or <i>multi-line</i>, depending on the 'flex-wrap' property. A <dfn>single-line</dfn> flexbox lays out all of its children in a single line, even if that would cause the flexbox to overflow its bounds. A <dfn>multi-line</dfn> flexbox breaks its <i>flexbox items</i> across multiple lines to avoid overflowing, similar to how text is broken onto a new line when it gets too wide to fit on the existing line. Every line contains at least one <i>flexbox item</i>, unless the flexbox itself is completely empty.</p>
alexmog@4725 255
alexmog@4725 256 <p>When additional lines are created, they are stacked in the flexbox in the <i>cross axis</i>. Each line is completely independent; flexible lengths and the 'flex-pack' and 'flex-align' properties only consider the items on a single line at a time. The <i>main size</i> of a line is the same as the <i>main size</i> of the flexbox's content box. The <i>cross size</i> of a line depends on whether the flexbox is <i>single-line</i> or <i>multi-line</i>: the <i>cross size</i> of the sole line in a <i>single-line</i> flexbox is the same as the <i>cross size</i> of the flexbox's content box, while the <i>cross size</i> of a line in a <i>multi-line</i> flexbox is the minimum size necessary to contain the <i>flexbox items</i> on the line, after aligning them with 'flex-align'. The lines themselves are then aligned within a flexbox with the 'flex-line-pack' property.</p>
alexmog@4725 257
alexmog@4725 258 <div class=example>
alexmog@4725 259 <p>This example shows four buttons that do not fit horizontally.</p>
alexmog@4725 260
alexmog@4725 261 <pre>&lt;style>
alexmog@4725 262 #div1 {
alexmog@4725 263 display: flexbox;
alexmog@4725 264 flex-flow: row wrap;
alexmog@4725 265 width: 300px;
alexmog@4725 266 }
alexmog@4725 267 button {
alexmog@4725 268 flex:80px 1;
alexmog@4725 269 }
alexmog@4725 270 &lt;style>
alexmog@4725 271
alexmog@4725 272 &lt;div id="div1">
alexmog@4725 273 &lt;button id="button1">Elephant&lt;/button>
alexmog@4725 274 &lt;button id="button2">Tiger&lt;/button>
alexmog@4725 275 &lt;button id="button3">Antelope&lt;/button>
alexmog@4725 276 &lt;button id="button4">Wildebeest&lt;/button>
alexmog@4725 277 &lt;/div></pre>
alexmog@4725 278
alexmog@4725 279 <p>The buttons are first set to their preferred widths, in this case 80 pixels. This will allow the first three buttons to fit in 240 pixels with 60 pixels left over of remaining space. Because the 'flex-flow' property specifies a multi-line flexbox (due to the ''wrap'' keyword appearing in its value), the flexbox will create an additional line to contain the last button.</p>
alexmog@4725 280
alexmog@4725 281 <p>Flexibility is applied to each element, separately for each line. The first line has 60 pixels of remaining space and all of the buttons have the same flexibility, so each of the three buttons on that line will receive 20 pixels of extra width, ending up 100px wide. The remaining button is on a line of its own and will stretch to the entire width of the line, or 300 pixels.</p>
alexmog@4725 282
alexmog@4725 283 <div style="width:300px; border:medium solid green; overflow: hidden;">
alexmog@4725 284 <button style="width:100px; float: left;">Elephant</button>
alexmog@4725 285 <button style="width:100px; float: left;">Tiger</button>
alexmog@4725 286 <button style="width:100px; float: left;">Antelope</button>
alexmog@4725 287 <button style="width:300px; float: left;">Wildebeest</button>
alexmog@4725 288 </div>
alexmog@4725 289
alexmog@4725 290 <p>If the box was resized, the buttons may rearrange onto different lines as necessary.</p>
alexmog@4725 291
alexmog@4725 292 <p>If the style rules in the example above were changed to the following:</p>
alexmog@4725 293
alexmog@4725 294 <pre>
alexmog@4725 295 #div1 {
alexmog@4725 296 display: flexbox;
alexmog@4725 297 flex-flow: row wrap;
alexmog@4725 298 flex-pack: center;
alexmog@4725 299 width: 300px;
alexmog@4725 300 }
alexmog@4725 301 button {
alexmog@4725 302 flex:80px 1;
alexmog@4725 303 max-width: 90px;
alexmog@4725 304 }</pre>
alexmog@4725 305
alexmog@4725 306 <p>Similar to the previous example, the first three buttons will fit on the first line, and the last button will wrap onto a new line. However, when the buttons attempt to flex they can only grow to 90px each, due to their 'max-width' property. This leaves 30px of free space on the first line and 210px of free space on the second line. Because 'flex-pack' is set to ''center'', the buttons will be centered on each line, with the free space split equally on either side.</p>
alexmog@4725 307
alexmog@4725 308 <div style="width:300px; border:medium solid green; text-align:center;">
alexmog@4725 309 <button style="width:90px; float: left; margin-left: 15px;">Elephant</button>
alexmog@4725 310 <button style="width:90px; float: left;">Tiger</button>
alexmog@4725 311 <button style="width:90px; float: left;">Antelope</button>
alexmog@4725 312 <button style="width:90px">Wildebeest</button>
alexmog@4725 313 </div>
alexmog@4725 314 </div>
alexmog@4725 315
alexmog@4725 316 <h2>
alexmog@4725 317 Ordering and Orientation</h2>
alexmog@4725 318
alexmog@4725 319 <p>The first level of flexbox functionality is the ability to lay out a flexbox's contents in any direction and in any order. This allows an author to trivially achieve effects that would previously have required complex or fragile methods, such as using the 'float' property to lay out a horizontal navigation bar (which then requires further effort with the 'clear' property or others to make the elements interact nicely with the rest of the page). This functionality is exposed through the 'flex-flow' and 'flex-order' properties.</p>
alexmog@4725 320
alexmog@4725 321 <h3 id='flex-direction'>
alexmog@4725 322 Flexbox Flow Direction: the 'flex-direction' property</h3>
alexmog@4725 323
alexmog@4725 324 <table class=propdef>
alexmog@4725 325 <tr>
alexmog@4725 326 <th>Name:</th>
alexmog@4725 327 <td><dfn>flex-direction</dfn>
alexmog@4725 328 <tr>
alexmog@4725 329 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 330 <td>row | row-reverse | column | column-reverse
alexmog@4725 331 <tr>
alexmog@4725 332 <th>Initial:
alexmog@4725 333 <td>row
alexmog@4725 334 <tr>
alexmog@4725 335 <th>Applies To:
alexmog@4725 336 <td>flexboxes
alexmog@4725 337 <tr>
alexmog@4725 338 <th>Inherited:
alexmog@4725 339 <td>no
alexmog@4725 340 <tr>
alexmog@4725 341 <th>Computed Value:
alexmog@4725 342 <td>specified value
alexmog@4725 343 <tr>
alexmog@4725 344 <th>Media:
alexmog@4725 345 <td>visual
alexmog@4725 346 <tr>
alexmog@4725 347 <th>Animatable:
alexmog@4725 348 <td>no
alexmog@4725 349 </table>
alexmog@4725 350
alexmog@4725 351 <p>The 'flex-direction' property specifies how <i>flexbox items</i> are placed in the flexbox, by setting the direction of the flexbox's <i>main axis</i>. This affects the direction that flexbox items are laid out in, and the meaning of the 'flex-pack' property.</p>
alexmog@4725 352
alexmog@4725 353 <dl>
alexmog@4725 354 <dt><dfn id='flex-flow-row'>row</dfn></dt>
alexmog@4725 355 <dd>The flexbox's <i>main axis</i> has the same orientation as the inline axis of the current writing mode (the direction that text is laid out in). The <i>main-start</i> and <i>main-end</i> directions are equivalent to the "start" and "end" directions, respectively, of the current writing mode.</dd>
alexmog@4725 356
alexmog@4725 357 <dt><dfn id='flex-flow-row-reverse'>row-reverse</dfn></dt>
alexmog@4725 358 <dd>Same as <i>row</i>, except the <i>main-start</i> and <i>main-end</i> directions are swapped.</dd>
alexmog@4725 359
alexmog@4725 360 <dt><dfn id='flex-flow-column'>column</dfn></dt>
alexmog@4725 361 <dd>The flexbox's <i>main axis</i> has the same orientation as the block axis of the current writing mode (the direction that blocks are laid out in). The <i>main-start</i> and <i>main-end</i> directions are equivalent to the "before" and "after" directions, respectively, of the current writing mode.</dd>
alexmog@4725 362
alexmog@4725 363 <dt><dfn id='flex-flow-column-reverse'>column-reverse</dfn></dt>
alexmog@4725 364 <dd>Same as <i>column</i>, except the <i>main-start</i> and <i>main-end</i> directions are swapped.</dd>
alexmog@4725 365 </dl>
alexmog@4725 366
alexmog@4725 367 <h3 id='flex-wrap'>
alexmog@4725 368 Flexbox Wrapping: the 'flex-wrap' property</h3>
alexmog@4725 369
alexmog@4725 370 <table class=propdef>
alexmog@4725 371 <tr>
alexmog@4725 372 <th>Name:</th>
alexmog@4725 373 <td><dfn>flex-wrap</dfn>
alexmog@4725 374 <tr>
alexmog@4725 375 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 376 <td>nowrap | wrap | wrap-reverse
alexmog@4725 377 <tr>
alexmog@4725 378 <th>Initial:
alexmog@4725 379 <td>nowrap
alexmog@4725 380 <tr>
alexmog@4725 381 <th>Applies To:
alexmog@4725 382 <td>flexboxes
alexmog@4725 383 <tr>
alexmog@4725 384 <th>Inherited:
alexmog@4725 385 <td>no
alexmog@4725 386 <tr>
alexmog@4725 387 <th>Computed Value:
alexmog@4725 388 <td>specified value
alexmog@4725 389 <tr>
alexmog@4725 390 <th>Media:
alexmog@4725 391 <td>visual
alexmog@4725 392 <tr>
alexmog@4725 393 <th>Animatable:
alexmog@4725 394 <td>no
alexmog@4725 395 </table>
alexmog@4725 396
alexmog@4725 397 <p>The 'flex-wrap' property controls whether the flexbox is <i>single-line</i> or <i>multi-line</i>, and the direction of the <i>cross axis</i>, which affects the direction new lines are stacked in and the meaning of the 'flex-align', 'flex-item-align', and 'flex-line-pack' properties.</p>
alexmog@4725 398
alexmog@4725 399 <dl>
alexmog@4725 400 <dt>nowrap</dt>
alexmog@4725 401 <dd>The flexbox is <i>single-line</i>. The <i>cross-start</i> direction is equivalent to either the "start" or "before" direction of the current writing mode, whichever is in the <i>cross-axis</i>, and the <i>cross-end</i> direction is the opposite direction of <i>cross-start</i>.
alexmog@4725 402 </dd>
alexmog@4725 403
alexmog@4725 404 <dt><dfn id='flex-flow-wrap'>wrap</dfn></dt>
alexmog@4725 405 <dd>The flexbox is <i>multi-line</i>. The <i>cross-start</i> direction is equivalent to either the "start" or "before" direction of the current writing mode, whichever is in the <i>cross-axis</i>, and the <i>cross-end</i> direction is the opposite direction of <i>cross-start</i>.</dd>
alexmog@4725 406
alexmog@4725 407 <dt><dfn id='flex-flow-wrap-reverse'>wrap-reverse</dfn></dt>
alexmog@4725 408 <dd>Same as <i>wrap</i>, except the <i>cross-start</i> and <i>cross-end</i> directions are swapped.</dd>
alexmog@4725 409 </dl>
alexmog@4725 410
alexmog@4725 411 <h3 id='flex-flow'>
alexmog@4725 412 Flex Direction and Wrap: the 'flex-flow' shorthand</h3>
alexmog@4725 413
alexmog@4725 414 <table class=propdef>
alexmog@4725 415 <tr>
alexmog@4725 416 <th>Name:</th>
alexmog@4725 417 <td><dfn>flex-flow</dfn>
alexmog@4725 418 <tr>
alexmog@4725 419 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 420 <td>&lt;&apos;flex-direction&apos;> || &lt;&apos;flex-wrap&apos;>
alexmog@4725 421 <tr>
alexmog@4725 422 <th>Initial:
alexmog@4725 423 <td>see individual properties
alexmog@4725 424 <tr>
alexmog@4725 425 <th>Applies To:
alexmog@4725 426 <td>flexboxes
alexmog@4725 427 <tr>
alexmog@4725 428 <th>Inherited:
alexmog@4725 429 <td>see individual properties
alexmog@4725 430 <tr>
alexmog@4725 431 <th>Computed Value:
alexmog@4725 432 <td>see individual properties
alexmog@4725 433 <tr>
alexmog@4725 434 <th>Media:
alexmog@4725 435 <td>visual
alexmog@4725 436 <tr>
alexmog@4725 437 <th>Animatable:
alexmog@4725 438 <td>no
alexmog@4725 439 </table>
alexmog@4725 440
alexmog@4725 441 <p>The 'flex-flow' property is a shorthand for setting the 'flex-direction' and 'flex-wrap' properties together.</p>
alexmog@4725 442
alexmog@4725 443 <div class="example">
alexmog@4725 444 <p>Some examples of valid flows:</p>
alexmog@4725 445
alexmog@4725 446 <table style="margin: 0 auto; vertical-align: middle; border-spacing: 2em 1em;">
alexmog@4725 447 <tr>
alexmog@4725 448 <td><pre>
alexmog@4725 449 div { flex-flow: row; }
alexmog@4725 450 /* Initial value. Main axis is
alexmog@4725 451 inline, no wrap. */</pre>
alexmog@4725 452 <td><img src='images/flex-flow1.svg' width=240 height=80>
alexmog@4725 453 <tr>
alexmog@4725 454 <td><pre>
alexmog@4725 455 div { flex-flow: column wrap; }
alexmog@4725 456 /* Main axis is block-direction and lines
alexmog@4725 457 wrap in the inline direction. For an
alexmog@4725 458 English page, the main axis is top-to-bottom
alexmog@4725 459 and lines wrap to the right. */</pre>
alexmog@4725 460 <td><img src='images/flex-flow2.svg' width=170 height=200>
alexmog@4725 461 <tr>
alexmog@4725 462 <td><pre>
alexmog@4725 463 div { writing-mode: vertical-rl;
alexmog@4725 464 flex-flow: column wrap-reverse; }
alexmog@4725 465 /* Main axis is block direction (right to
alexmog@4725 466 left). New lines wrap upwards. */</pre>
alexmog@4725 467 <td><img src='images/flex-flow3.svg' width=200 height=170>
alexmog@4725 468 </table>
alexmog@4725 469 </div>
alexmog@4725 470
alexmog@4725 471
alexmog@4725 472 <h3 id='flex-order'>
alexmog@4725 473 Display Order: the 'flex-order' property</h3>
alexmog@4725 474
alexmog@4725 475 <p><i>Flexbox items</i> are, by default, displayed and laid out in the same order as they appear in the source document. The 'flex-order' property may be used to change this ordering.</p>
alexmog@4725 476
alexmog@4725 477 <table class=propdef>
alexmog@4725 478 <tr>
alexmog@4725 479 <th>Name:
alexmog@4725 480 <td><dfn>flex-order</dfn>
alexmog@4725 481 <tr>
alexmog@4725 482 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 483 <td>&lt;number>
alexmog@4725 484 <tr>
alexmog@4725 485 <th>Initial:
alexmog@4725 486 <td>0
alexmog@4725 487 <tr>
alexmog@4725 488 <th>Applies to:
alexmog@4725 489 <td><i>flexbox items</i></td>
alexmog@4725 490 <tr>
alexmog@4725 491 <th>Inherited:
alexmog@4725 492 <td>no
alexmog@4725 493 <tr>
alexmog@4725 494 <th>Computed value:
alexmog@4725 495 <td>specified value
alexmog@4725 496 <tr>
alexmog@4725 497 <th>Media:
alexmog@4725 498 <td>visual
alexmog@4725 499 <tr>
alexmog@4725 500 <th>Animatable:
alexmog@4725 501 <td>yes
alexmog@4725 502 </table>
alexmog@4725 503
alexmog@4725 504 <p>The 'flex-order' property assigns <i>flexbox items</i> to ordinal groups.</p>
alexmog@4725 505
alexmog@4725 506 <p>Ordinal groups control the order in which <i>flexbox items</i> appear. A flexbox will lay out its content starting from the lowest numbered ordinal group and going up. Items with the same ordinal group are laid out in the order they appear in the source document. 'flex-order' has no effect on stacking/layering; elements must still be drawn over/under each other based on document order, 'z-index', and other relevant means.</p>
alexmog@4725 507
alexmog@4725 508 <div class='example'>
alexmog@4725 509 <p>The following figure shows a simple tabbed interface, where the tab for the active pane is always in front:</p>
alexmog@4725 510
alexmog@4725 511 <div class='figure'><img src="images/flex-order-example.png"></div>
alexmog@4725 512
alexmog@4725 513 <p>This could be implemented with the following CSS (showing only the flexbox-relevant code):</p>
alexmog@4725 514
alexmog@4725 515 <pre>
alexmog@4725 516 .tabs {
alexmog@4725 517 display: flexbox;
alexmog@4725 518 }
alexmog@4725 519 .tabs > .current {
alexmog@4725 520 flex-order: -1; /* Lower than the default of 0 */
alexmog@4725 521 }</pre>
alexmog@4725 522
alexmog@4725 523 </div>
alexmog@4725 524
alexmog@4725 525 <div class='example'>
alexmog@4725 526 <p>Many web pages have a similar shape in the markup, with a header on top, a footer on bottom, and then a content area and one or two additional columns in the middle. Generally, it's desirable that the content come first in the page's source code, before the additional columns. However, this makes many common designs, such as simply having the additional columns on the left and the content area on the right, difficult to achieve. This has been addressed in many ways over the years, often going by the name "Holy Grail Layout" when there are two additional columns. 'flex-order' makes this trivial. For example, take the following sketch of a page's code and desired layout:</p>
alexmog@4725 527
alexmog@4725 528 <div class='code-and-figure'>
alexmog@4725 529 <div><pre>
alexmog@4725 530 &lt;!DOCTYPE html>
alexmog@4725 531 &lt;header>...&lt;/header>
alexmog@4725 532 &lt;div id='main'>
alexmog@4725 533 &lt;article>...&lt;/article>
alexmog@4725 534 &lt;nav>...&lt;/nav>
alexmog@4725 535 &lt;aside>...&lt;/aside>
alexmog@4725 536 &lt;/div>
alexmog@4725 537 &lt;footer>...&lt;/footer></pre></div>
alexmog@4725 538 <div><img src="images/flex-order-page.svg" width=400 height=360></div>
alexmog@4725 539 </div>
alexmog@4725 540
alexmog@4725 541 <p>This layout can be easily achieved with Flexbox:</p>
alexmog@4725 542
alexmog@4725 543 <pre>
alexmog@4725 544 #main { display: flexbox; }
alexmog@4725 545 #main > article { flex:1; flex-order: 2; }
alexmog@4725 546 #main > nav { width: 200px; flex-order: 1; }
alexmog@4725 547 #main > aside { width: 200px; flex-order: 3; }</pre>
alexmog@4725 548
alexmog@4725 549 <p>As an added bonus, the columns will all be equal-height by default, and the main content will be as wide as necessary to fill the screen. Additionally, this can then be combined with media queries to switch to an all-vertical layout on narrow screens:</p>
alexmog@4725 550
alexmog@4725 551 <pre>
alexmog@4725 552 @media all and (max-width: 600px) {
alexmog@4725 553 /* Too narrow to support three columns */
alexmog@4725 554 #main { flex-flow: column; }
alexmog@4725 555 #main > article, #main > nav, #main > aside {
alexmog@4725 556 /* Return them to document order */
alexmog@4725 557 flex-order: 0; width: auto;
alexmog@4725 558 }
alexmog@4725 559 }</pre>
alexmog@4725 560
alexmog@4725 561 <p><small>(Further use of multiline flexboxes to achieve even more intelligent wrapping left as an exercise for the reader.)</small></p>
alexmog@4725 562 </div>
alexmog@4725 563
alexmog@4725 564
alexmog@4725 565 <h2 id='flexibility'>
alexmog@4725 566 Flexibility: the 'flex' property</h2>
alexmog@4725 567
alexmog@4725 568 <p>The defining aspect of flexbox layout is the ability to make the <i>flexbox items</i> "flex", altering their width or height to fill the available space. This is done by using a 'flex' property. A flexbox distributes free space to its items proportional to their positive flexibility, or shrinks them to prevent overflow proportional to their negative flexibility.</p>
alexmog@4725 569
alexmog@4725 570 <table class=propdef>
alexmog@4725 571 <tr>
alexmog@4725 572 <th>Name:
alexmog@4725 573 <td><dfn>flex</dfn>
alexmog@4725 574 <tr>
alexmog@4725 575 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 576 <td>[ [ &lt;pos-flex> &lt;neg-flex>? ] || &lt;preferred-size> ] | none
alexmog@4725 577 <tr>
alexmog@4725 578 <th>Initial:
alexmog@4725 579 <td>none
alexmog@4725 580 <tr>
alexmog@4725 581 <th>Applies to:
alexmog@4725 582 <td>flexbox items
alexmog@4725 583 <tr>
alexmog@4725 584 <th>Inherited:
alexmog@4725 585 <td>no
alexmog@4725 586 <tr>
alexmog@4725 587 <th>Computed Value:
alexmog@4725 588 <td>specified value
alexmog@4725 589 <tr>
alexmog@4725 590 <th>Media:
alexmog@4725 591 <td>visual
alexmog@4725 592 <tr>
alexmog@4725 593 <th>Animatable:
alexmog@4725 594 <td>yes
alexmog@4725 595 </table>
alexmog@4725 596
alexmog@4725 597 <p>The 'flex' property specifies the parameters of a <dfn title="flexible length|flexible lengths|flexible length's">flexible length</dfn>: the <dfn id="positive-flexibility" title="positive flexibility">positive</dfn> and <dfn>negative flexibility</dfn>, and the <dfn>preferred size</dfn>.</p>
alexmog@4725 598
alexmog@4725 599 <p><code>&lt;pos-flex></code> and <code>&lt;neg-flex></code> are non-negative <code>&lt;number>s</code>. The <code>&lt;pos-flex></code> component sets the <i>positive flexibility</i>; if omitted, the <i>positive flexibility</i> defaults to ''1''. The <code>&lt;neg-flex></code> component sets the <i>negative flexibility</i>; if omitted, it defaults to ''0''. </p>
alexmog@4725 600 <p> The <code>&lt;preferred-size></code> component sets the preferred size. It can be set to any value that would be valid in the 'width' or 'height' property,
alexmog@4725 601 except values that are not applicable to a component value (of values
alexmog@4725 602 defined in CSS2.1, only &#39;inherit&#39; is not valid for <code>&lt;preferred-size></code>; in the future other values may be introduced that are not applicable as length component).
alexmog@4725 603 If omitted, the preferred size defaults to ''0px''. If set to 'auto', the value of 'width' or 'height' (whichever is in parallel to main axis) is used as preferred size.</p>
alexmog@4725 604 <p> &nbsp;If the <code>&lt;preferred-size></code> is ''0'', it <strong>must</strong> be specified with a unit (like ''0px'') to avoid ambiguity; unitless zero will either be interpreted as as one of the flexibilities, or is a syntax error.</p>
alexmog@4725 605
alexmog@4725 606 <p>The keyword 'none' is equivalent to "0 0 auto". </p>
alexmog@4725 607
alexmog@4725 608
alexmog@4725 609 <p>A ''&lt;flex>'' value is transitionable, by transitioning the <i>preferred size</i>, <i>positive flexibility</i>, and <i>negative flexibility</i> independently. ''&lt;flex>'' can also transition to and from a &lt;length>, by treating the length as if it were a flexible length with a positive and negative flexibility of zero and a preferred size of the length.</p>
alexmog@4725 610
alexmog@4725 611 <div class='example'>
alexmog@4725 612 <p>Flexibility allows elements to respond directly to the available space,
alexmog@4725 613 optionally taking into account size of content:</p>
alexmog@4725 614
alexmog@4725 615 <pre>
alexmog@4725 616 &lt;!DOCTYPE html>
alexmog@4725 617 &lt;style>
alexmog@4725 618 div { display:flexbox; outline:1px solid silver; }
alexmog@4725 619 p { flex:1 auto; margin:1em; background:gold; }
alexmog@4725 620 &lt;/style&gt;
alexmog@4725 621 &lt;div&gt;
alexmog@4725 622 &lt;p&gt;&quot;flexing&quot;&lt;/p&gt;
alexmog@4725 623 &lt;p&gt;allows the items to get bigger&lt;/p&gt;
alexmog@4725 624 &lt;p&gt;or&lt;/p&gt;
alexmog@4725 625 &lt;p&gt;smaller&lt;/p&gt;
alexmog@4725 626 &lt;/div&gt;
alexmog@4725 627 </pre>
alexmog@4725 628
alexmog@4725 629 <img src="images/wp7zxxyu.gif" alt="items with equal flexibility extend by equal amount">
alexmog@4725 630
alexmog@4725 631 </div>
alexmog@4725 632
alexmog@4725 633 <h2 id='alignment'>
alexmog@4725 634 Alignment</h2>
alexmog@4725 635
alexmog@4725 636 <p>After a flexbox's contents have finished their flexing and dimensions of
alexmog@4725 637 margin boxes of all flexbox items are finalized, they can be aligned in both the <i>main axis</i> with 'flex-pack' and the <i>cross axis</i> with 'flex-align' and 'flex-item-align'. These properties make many common types of alignment trivial, including some things that were very difficult in CSS 2.1, like horizontal and vertical centering.</p>
alexmog@4725 638
alexmog@4725 639
alexmog@4725 640 <h3 id='flex-pack'>
alexmog@4725 641 Axis Alignment: the 'flex-pack' property</h3>
alexmog@4725 642
alexmog@4725 643 <table class=propdef>
alexmog@4725 644 <tr>
alexmog@4725 645 <th>Name:
alexmog@4725 646 <td><dfn>flex-pack</dfn>
alexmog@4725 647 <tr>
alexmog@4725 648 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 649 <td>start | end | center | justify | distribute
alexmog@4725 650 <tr>
alexmog@4725 651 <th>Initial:
alexmog@4725 652 <td>start
alexmog@4725 653 <tr>
alexmog@4725 654 <th>Applies to:
alexmog@4725 655 <td>flexboxes
alexmog@4725 656 <tr>
alexmog@4725 657 <th>Inherited:
alexmog@4725 658 <td>no
alexmog@4725 659 <tr>
alexmog@4725 660 <th>Computed Value:
alexmog@4725 661 <td>specified value
alexmog@4725 662 <tr>
alexmog@4725 663 <th>Media:
alexmog@4725 664 <td>visual
alexmog@4725 665 <tr>
alexmog@4725 666 <th>Animatable:
alexmog@4725 667 <td>no
alexmog@4725 668 </table>
alexmog@4725 669
alexmog@4725 670 <p>The 'flex-pack' property aligns <i>flexbox items</i> in the <i>main axis</i> of the current line of the flexbox. This is done <em title=''>after</em> any flexible lengths
alexmog@4725 671 and any auto margins have been resolved. Typically it helps distribute extra free space leftover when either all the <i>flexbox items</i> on a line are inflexible, or are flexible but have reach their maximum size, but it also exerts some control over the alignment of items when they overflow the line.</p>
alexmog@4725 672
alexmog@4725 673 <dl>
alexmog@4725 674 <dt><dfn id='flex-pack-start'>start</dfn></dt>
alexmog@4725 675 <dd><i>Flexbox items</i> are packed toward the start of the line. The <i>main-start</i> margin edge of the first <i>flexbox item</i> on the line is placed flush with the <i>main-start</i> edge of the line, and each subsequent <i>flexbox item</i> is placed flush with the preceding item.</dd>
alexmog@4725 676
alexmog@4725 677 <dt><dfn id='flex-pack-end'>end</dfn></dt>
alexmog@4725 678 <dd><i>Flexbox items</i> are packed toward the end of the line. The <i>main-end</i> margin edge of the last <i>flexbox item</i> is placed flush with the <i>main-end</i> edge of the line, and each preceding <i>flexbox item</i> is placed flush with the subsequent item.</dd>
alexmog@4725 679
alexmog@4725 680 <dt><dfn id='flex-pack-center'>center</dfn></dt>
alexmog@4725 681 <dd><i>Flexbox items</i> are packed toward the center of the line. The <i>flexbox items</i> on the line are placed flush with each other and aligned in the center of the line, with equal amounts of empty space between the <i>main-start</i> edge of the line and the first item on the line and between the <i>main-end</i> edge of the line and the last item on the line. (If the leftover free-space is negative, the <i>flexbox items</i> will overflow equally in both directions.)</dd>
alexmog@4725 682
alexmog@4725 683 <dt><dfn id='flex-pack-justify'>justify</dfn></dt>
alexmog@4725 684 <dd><i>Flexbox items</i> are evenly distributed in the line. If the leftover free-space is negative or there is only a single <i>flexbox item</i> on the line, this value is identical to ''start''. Otherwise, the <i>main-start</i> margin edge of the first <i>flexbox item</i> on the line is placed flush with the <i>main-start</i> edge of the line, the <i>main-end</i> margin edge of the last <i>flexbox item</i> on the line is placed flush with the <i>main-end</i> edge of the line, and the remaining <i>flexbox items</i> on the line are distributed so that the empty space between any two adjacent items is the same.</dd>
alexmog@4725 685
alexmog@4725 686 <dt><dfn id='flex-pack-distribute'>distribute</dfn></dt>
alexmog@4725 687 <dd><i>Flexbox items</i> are evenly distributed in the line, with half-size spaces on either end. If the leftover free-space is negative or there is only a single <i>flexbox item</i> on the line, this value is identical to ''center''. Otherwise, the <i>flexbox items</i> on the line are distributed such that the empty space between any two adjacent <i>flexbox items</i> on the line is the same, and the empty space before the first and after the last <i>flexbox items</i> on the line are half the size of the other empty spaces.</dd>
alexmog@4725 688 </dl>
alexmog@4725 689
alexmog@4725 690 <div class="figure">
alexmog@4725 691 <img src="images/flex-pack.svg" width=504 height=270>
alexmog@4725 692 <p class='caption'>An illustration of the five 'flex-pack' keywords and their effects on a flexbox with three colored items.</p>
alexmog@4725 693 </div>
alexmog@4725 694
alexmog@4725 695
alexmog@4725 696 <h3 id='flex-align'>
alexmog@4725 697 Cross Axis Alignment: the 'flex-align' and 'flex-item-align' properties</h3>
alexmog@4725 698
alexmog@4725 699 <table class=propdef>
alexmog@4725 700 <tr>
alexmog@4725 701 <th>Name:
alexmog@4725 702 <td><dfn>flex-align</dfn>
alexmog@4725 703 <tr>
alexmog@4725 704 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 705 <td>start | end | center | baseline | stretch
alexmog@4725 706 <tr>
alexmog@4725 707 <th>Initial:
alexmog@4725 708 <td>stretch
alexmog@4725 709 <tr>
alexmog@4725 710 <th>Applies to:
alexmog@4725 711 <td>flexboxes
alexmog@4725 712 <tr>
alexmog@4725 713 <th>Inherited:
alexmog@4725 714 <td>no
alexmog@4725 715 <tr>
alexmog@4725 716 <th>Computed Value:
alexmog@4725 717 <td>specified value
alexmog@4725 718 <tr>
alexmog@4725 719 <th>Media:
alexmog@4725 720 <td>visual
alexmog@4725 721 <tr>
alexmog@4725 722 <th>Animatable:
alexmog@4725 723 <td>no
alexmog@4725 724 </table>
alexmog@4725 725
alexmog@4725 726 <table class=propdef>
alexmog@4725 727 <tr>
alexmog@4725 728 <th>Name:
alexmog@4725 729 <td><dfn>flex-item-align</dfn>
alexmog@4725 730 <tr>
alexmog@4725 731 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 732 <td>auto | start | end | center | baseline | stretch
alexmog@4725 733 <tr>
alexmog@4725 734 <th>Initial:
alexmog@4725 735 <td>auto
alexmog@4725 736 <tr>
alexmog@4725 737 <th>Applies to:
alexmog@4725 738 <td><i>flexbox items</i>
alexmog@4725 739 <tr>
alexmog@4725 740 <th>Inherited:
alexmog@4725 741 <td>no
alexmog@4725 742 <tr>
alexmog@4725 743 <th>Computed Value:
alexmog@4725 744 <td>''auto'' computes to parent's 'flex-align'; otherwise as specified
alexmog@4725 745 <tr>
alexmog@4725 746 <th>Media:
alexmog@4725 747 <td>visual
alexmog@4725 748 <tr>
alexmog@4725 749 <th>Animatable:
alexmog@4725 750 <td>no
alexmog@4725 751 </table>
alexmog@4725 752
alexmog@4725 753 <p><i>Flexbox items</i> can be aligned in the <i>cross axis</i> of the current line of the flexbox, similar to 'flex-pack' but in the perpendicular direction. 'flex-align' sets the default alignment for all of the flexbox's <i title="flexbox items">items</i>, including anonymous <i>flexbox items</i>. 'flex-item-align' allows this default alignment to be overridden for individual <i>flexbox items</i> (for anonymous flexbox items, 'flex-item-align' always matches the value of 'flex-align' on their associated flexbox).</p>
alexmog@4725 754
alexmog@4725 755 <p>A value of <dfn id="flex-item-align-auto">''auto''</dfn> for 'flex-item-align' computes to the value of 'flex-align' on the <i>flexbox item's</i> flexbox. The alignments are defined as:</p>
alexmog@4725 756
alexmog@4725 757 <dl>
alexmog@4725 758 <dt><dfn id="flex-align-start">start</dfn></dt>
alexmog@4725 759 <dd>The <i>cross-start</i> margin edge of the <i>flexbox item</i> is placed flush with the <i>cross-start</i> edge of the line.</dd>
alexmog@4725 760
alexmog@4725 761 <dt><dfn id="flex-align-end">end</dfn></dt>
alexmog@4725 762 <dd>The <i>cross-end</i> margin edge of the <i>flexbox item</i> is placed flush with the <i>cross-end</i> edge of the line.</dd>
alexmog@4725 763
alexmog@4725 764 <dt><dfn id="flex-align-center">center</dfn></dt>
alexmog@4725 765 <dd>The <i>flexbox item's</i> margin box is centered in the <i>cross axis</i> within the line. (If the <i>cross size</i> of the flexbox is less than that of the <i>flexbox item</i>, it will overflow equally in both directions.)</dd>
alexmog@4725 766
alexmog@4725 767 <dt><dfn id="flex-align-baseline">baseline</dfn></dt>
alexmog@4725 768 <dd>
alexmog@4725 769 <p>If the <i>flexbox item's</i> inline axis is the same as the <i>cross axis</i>, this value is identical to ''start''.</p>
alexmog@4725 770
alexmog@4725 771 <p>Otherwise, all <i>flexbox items</i> on the line with an alignment of ''baseline'' that don't run afoul of the previous paragraph are aligned such that their baselines align, and the item with the largest distance between its baseline and its <i>cross-start</i> margin edge is placed flush against the <i>cross-start</i> edge of the line.</p>
alexmog@4725 772 </dd>
alexmog@4725 773
alexmog@4725 774 <dt><dfn id="flex-align-stretch">stretch</dfn></dt>
alexmog@4725 775 <dd>
alexmog@4725 776 <p>If the <i>cross size property</i> of the <i>flexbox item</i> is ''auto'', it resolves to the length necessary to make the <i>cross size</i> of the item's margin box the same size as the line, while still respecting 'min/max-width/height' constraints as normal.</p>
alexmog@4725 777
alexmog@4725 778 <p>The <i>cross-start</i> margin edge of the <i>flexbox item</i> is placed flush with the <i>cross-start</i> edge of the line.</p>
alexmog@4725 779 </dd>
alexmog@4725 780 </dl>
alexmog@4725 781
alexmog@4725 782 <div class='figure'>
alexmog@4725 783 <img src="images/flex-align.svg" width=508 height=377>
alexmog@4725 784 <p class='caption'>An illustration of the five 'flex-align' keywords and their effects on a flexbox with four colored items.</p>
alexmog@4725 785 </div>
alexmog@4725 786
alexmog@4725 787 <div class=example>
alexmog@4725 788 <p>By using a vertical flexbox and 'flex-align', we can achieve behavior very close to HTML's <code>&lt;center></code> element:</p>
alexmog@4725 789
alexmog@4725 790 <div class='code-and-figure'>
alexmog@4725 791 <div><pre>
alexmog@4725 792 &lt;div>
alexmog@4725 793 &lt;p>foo foo foo foo&lt;/p>
alexmog@4725 794 &lt;p>bar bar&lt;br>bar bar&lt;/p>
alexmog@4725 795 &lt;p>foo foo foo foo foo foo foo
alexmog@4725 796 foo foo foo foo foo&lt;/p>
alexmog@4725 797 &lt;/div>
alexmog@4725 798 &lt;style>
alexmog@4725 799 div {
alexmog@4725 800 display: flexbox;
alexmog@4725 801 flex-flow: column;
alexmog@4725 802 flex-align: center;
alexmog@4725 803 width: 200px;
alexmog@4725 804 }
alexmog@4725 805 &lt;/style></pre></div>
alexmog@4725 806 <div><p><img alt="" src="images/basic-vertical-flexbox.png"></p></div>
alexmog@4725 807 </div>
alexmog@4725 808 </div>
alexmog@4725 809
alexmog@4725 810
alexmog@4725 811 <h3 id='auto-margins'>
alexmog@4725 812 Resolving &#39;auto&#39; margins</h3>
alexmog@4725 813 <p>
alexmog@4725 814 Margins on flexbox items can be set to &#39;auto&#39;, with effect very similar to auto
alexmog@4725 815 margins in normal flow. </p>
alexmog@4725 816 <ul>
alexmog@4725 817 <li>Through calculations of preferred sizes and flexible lengths, auto
alexmog@4725 818 margins are considered to be zero.</li>
alexmog@4725 819 <li>&nbsp;Immediately <em>before</em> pack and align steps, if there are any
alexmog@4725 820 auto margins on items in the direction of alignment and there is positive
alexmog@4725 821 free space, the free space is distributed equally to the auto margins. </li>
alexmog@4725 822 <li>If free space was distributed to auto margins, the following pack or align
alexmog@4725 823 step has no effect.</li>
alexmog@4725 824 </ul>
alexmog@4725 825 <div class="example">
alexmog@4725 826 <p>Auto margins can be used for simple alignment or for fine control.</p>
alexmog@4725 827 <p>Note that auto margins work consistently in both dimensions, so a simple
alexmog@4725 828 markup like this</p>
alexmog@4725 829 <pre>div { display:flexbox;
alexmog@4725 830 width:4em; height:4em; background:silver;
alexmog@4725 831 }
alexmog@4725 832 p { margin:auto; }
alexmog@4725 833 &lt;div&gt;&lt;p&gt;OK&lt;/p&gt;&lt;/div&gt;</pre>
alexmog@4725 834 <p>will center the single child:
alexmog@4725 835 <img alt="image of square OK button" height="82" src="images/OK.png" width="82"></p>
alexmog@4725 836 <p>And this</p>
alexmog@4725 837
alexmog@4725 838 <pre>div { display:flexbox;
alexmog@4725 839 width:calc(100% - 4em); height:calc(100% - 4em);
alexmog@4725 840 border: 1em solid blue; border-radius:50%;
alexmog@4725 841 margin:auto;
alexmog@4725 842 }
alexmog@4725 843 div#demo { width:9em; height:9em; }</pre>
alexmog@4725 844 <pre>&lt;div id=&quot;demo&quot;&gt;&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;</pre>
alexmog@4725 845 <p>will produce nested centered boxes:
alexmog@4725 846 <img alt="concentric blue circles" height="191" src="images/target.png" width="210"></p>
alexmog@4725 847 </div>
alexmog@4725 848
alexmog@4725 849 <h3 id='flex-line-pack'>
alexmog@4725 850 'flex-line-pack' property</h3>
alexmog@4725 851
alexmog@4725 852 <table class=propdef>
alexmog@4725 853 <tr>
alexmog@4725 854 <th>Name:
alexmog@4725 855 <td><dfn>flex-line-pack</dfn>
alexmog@4725 856 <tr>
alexmog@4725 857 <th><a href="http://dev.w3.org/csswg/css-module/#values">Value</a>:
alexmog@4725 858 <td>start | end | center | justify | distribute | stretch
alexmog@4725 859 <tr>
alexmog@4725 860 <th>Initial:
alexmog@4725 861 <td>stretch
alexmog@4725 862 <tr>
alexmog@4725 863 <th>Applies to:
alexmog@4725 864 <td><i>multi-line</i> flexboxes
alexmog@4725 865 <tr>
alexmog@4725 866 <th>Inherited:
alexmog@4725 867 <td>no
alexmog@4725 868 <tr>
alexmog@4725 869 <th>Computed Value:
alexmog@4725 870 <td>specified value
alexmog@4725 871 <tr>
alexmog@4725 872 <th>Media:
alexmog@4725 873 <td>visual
alexmog@4725 874 <tr>
alexmog@4725 875 <th>Animatable:
alexmog@4725 876 <td>no
alexmog@4725 877 </table>
alexmog@4725 878
alexmog@4725 879 <p>The 'flex-line-pack' property aligns a flexbox's lines within the flexbox when there is extra space in the <i>cross axis</i>, similar to how 'flex-pack' aligns individual items within the <i>main axis</i>:</p>
alexmog@4725 880
alexmog@4725 881 <dl>
alexmog@4725 882 <dt><dfn id='flex-line-pack-start'>start</dfn></dt>
alexmog@4725 883 <dd>Lines are packed toward the start of the flexbox. The <i>cross-start</i> edge of the first line in the flexbox is placed flush with the <i>cross-start</i> edge of the flexbox, and each subsequent line is placed flush with the preceding line.</dd>
alexmog@4725 884
alexmog@4725 885 <dt><dfn id='flex-line-pack-end'>end</dfn></dt>
alexmog@4725 886 <dd>Lines are packed toward the end of the flexbox. The <i>cross-end</i> edge of the last line is placed flush with the <i>cross-end</i> edge of the flexbox, and each preceding line is placed flush with the subsequent line.</dd>
alexmog@4725 887
alexmog@4725 888 <dt><dfn id='flex-line-pack-center'>center</dfn></dt>
alexmog@4725 889 <dd>Lines are packed toward the center of the flexbox. The lines in the flexbox are placed flush with each other and aligned in the center of the flexbox, with equal amounts of empty space between the <i>cross-start</i> content edge of the flexbox and the first line in the flexbox and between the <i>cross-end</i> content edge of the flexbox and the last line in the flexbox. (If the leftover free-space is negative, the lines will overflow equally in both directions.)</dd>
alexmog@4725 890
alexmog@4725 891 <dt><dfn id='flex-line-pack-justify'>justify</dfn></dt>
alexmog@4725 892 <dd>Lines are evenly distributed in the flexbox. If the leftover free-space is negative or there is only a single line in the flexbox, this value is identical to ''start''. Otherwise, the <i>cross-start</i> edge of the first line in the flexbox is placed flush with the <i>cross-start</i> content edge of the flexbox, the <i>cross-end</i> edge of the last line in the flexbox is placed flush with the <i>cross-end</i> content edge of the flexbox, and the remaining lines in the flexbox are distributed so that the empty space between any two adjacent lines is the same.</dd>
alexmog@4725 893
alexmog@4725 894 <dt><dfn id='flex-line-pack-distribute'>distribute</dfn></dt>
alexmog@4725 895 <dd>Lines are evenly distributed in the flexbox, with half-size spaces on either end. If the leftover free-space is negative or there is only a single line in the flexbox, this value is identical to ''center''. Otherwise, the lines in the flexbox are distributed such that the empty space between any two adjacent lines is the same, and the empty space before the first and after the last lines in the flexbox are half the size of the other empty spaces.</dd>
alexmog@4725 896
alexmog@4725 897 <dt><dfn id='flex-line-pack-stretch'>stretch</dfn></dt>
alexmog@4725 898 <dd>Lines stretch to take up the remaining space. If the leftover free-space is negative, this value is identical to ''start''. Otherwise, the free-space is split equally between all of the lines, increasing their cross size.
alexmog@4725 899 </dl>
alexmog@4725 900
alexmog@4725 901 <p class='note'>Note: Only <i>multi-line</i> flexboxes ever have free space in the <i>cross axis</i> for lines to be aligned in, because in a <i>single-line</i> flexbox the sole line automatically stretches to fill the space.</p>
alexmog@4725 902
alexmog@4725 903 <p class="issue">TODO: examples</p>
alexmog@4725 904
alexmog@4725 905
alexmog@4725 906 <h2 id='layout-algorithm'>
alexmog@4725 907 Flexbox Layout Algorithm</h2>
alexmog@4725 908
alexmog@4725 909 <p>This section contains normative algorithms detailing the exact layout behavior of a flexbox and its contents. The algorithms here were designed to optimize readability and theoretical simplicity, and may not necessarily be the most efficient. Implementations may use whatever actual algorithms they wish, but must produce the same results as the algorithms described here.</p>
alexmog@4725 910
alexmog@4725 911 <div class=note>
alexmog@4725 912 <p>This note will outline the general structure of the layout algorithm, before I go into the ugly details below, to aid in reading the relatively-long and complex algorithm.</p>
alexmog@4725 913
alexmog@4725 914 <ol>
alexmog@4725 915 <li value=0>Generate anonymous flexbox items as necessary.</li>
alexmog@4725 916
alexmog@4725 917 <li>Reorder flexbox items according to 'flex-order'.</li>
alexmog@4725 918
alexmog@4725 919 <li>Find the hypothetical main size of every flexbox item.</li>
alexmog@4725 920
alexmog@4725 921 <li>Linebreak the flexbox, if it's multi-line.</li>
alexmog@4725 922
alexmog@4725 923 <li>Based on the hypothetical sizes of the items, find the real main size of the flexbox.</li>
alexmog@4725 924
alexmog@4725 925 <li>Resolve any flexible lengths. All items now have a real main size.</li>
alexmog@4725 926
alexmog@4725 927 <li>Update layout for the items based on their real main sizes, and determine their hypothetical cross size.</li>
alexmog@4725 928
alexmog@4725 929 <li>Find the real cross size of the flexbox and its lines.</li>
alexmog@4725 930
alexmog@4725 931 <li>Align the lines, per 'flex-line-pack'.</li>
alexmog@4725 932
alexmog@4725 933 <li>Align in the cross axis, per 'flex-align'.</li>
alexmog@4725 934
alexmog@4725 935 <li>Update layout for the items based on their real cross sizes.</li>
alexmog@4725 936
alexmog@4725 937 <li>Align in the main axis, per 'flex-pack'.</li>
alexmog@4725 938 </ol>
alexmog@4725 939 </div>
alexmog@4725 940
alexmog@4725 941 <p>This section is mainly intended for implementors. Authors writing web pages should generally be served well by the individual property descriptions, and do not need to read this section unless they have a deep-seated urge to understand arcane details of CSS layout.</p>
alexmog@4725 942
alexmog@4725 943 <p>To lay out a flexbox and its contents, follow these steps:</p>
alexmog@4725 944
alexmog@4725 945 <ol>
alexmog@4725 946 <li value=0>Generate anonymous flexbox items around runs of contiguous inline content in the flexbox, as described in the <a href="#flex-items">Flexbox Items</a> section.</li>
alexmog@4725 947
alexmog@4725 948 <li>Re-order the flexbox items according to their 'flex-order'. The items with the lowest (most negative) 'flex-order' values are first in the ordering. If multiple items share a 'flex-order' value, they're ordered by document order. This affects the order in which the flexbox items generate boxes in the box-tree, and how the rest of this algorithm deals with the items.</li>
alexmog@4725 949
alexmog@4725 950 <li>
alexmog@4725 951 Determine the hypothetical main size of items:
alexmog@4725 952
alexmog@4725 953 <ol>
alexmog@4725 954 <li>If item has a definite preferred size, it is the hypothetical main size. </li>
alexmog@4725 955
alexmog@4725 956 <li>
alexmog@4725 957 <p>Otherwise layout the flexbox items using the shrink-to-fit algorithm.</p>
alexmog@4725 958
alexmog@4725 959 <p>Calculation of the shrink-to-fit width is similar to calculating the width of a table cell using the automatic table layout algorithm. Roughly: calculate the preferred width by formatting the content without breaking lines other than where explicit line breaks occur, and also calculate the preferred minimum width, e.g., by trying all possible line breaks. This module doesn&#39;t define the exact algorithm, but it is expected that the shrink-to-fit size is calculated the same way as it is for floats, except in this case it is not affected by available space.</p>
alexmog@4725 960
alexmog@4725 961 <div class="issue"><p>TODO: define shrink-to-fit. It works
alexmog@4725 962 differently in row/column flexboxes:</p>
alexmog@4725 963 <ul>
alexmog@4725 964 <li>In horizontal, STF is max-content. </li>
alexmog@4725 965 <li>In vertical, cross-axis
alexmog@4725 966 alignment has to happen first, then main-axis STF size can
alexmog@4725 967 be calculated. In multi-line vertical (tricky case), auto
alexmog@4725 968 sizes on cross axis are resolved as if it was
alexmog@4725 969 single-line.</li>
alexmog@4725 970 </ul>
alexmog@4725 971 </div>
alexmog@4725 972 </li>
alexmog@4725 973 </ol>
alexmog@4725 974
alexmog@4725 975 <p><em>Do not apply min/max-width/height constraints to the preferred size of flexible lengths - those constraints are handled elsewhere in this algorithm, and doing so will produce incorrect results. </em></p>
alexmog@4725 976 </li>
alexmog@4725 977
alexmog@4725 978 <li>
alexmog@4725 979 <p>If the flexbox is single-line, collect all the flexbox items into a single flexbox line.</p>
alexmog@4725 980 </li>
alexmog@4725 981
alexmog@4725 982 <li>
alexmog@4725 983 <p>If the flexbox is multi-line, group the flexbox items into multiple lines:</p>
alexmog@4725 984
alexmog@4725 985 <ol>
alexmog@4725 986 <li>
alexmog@4725 987 <p>Determine the maximum line length, based on the main size of the flexbox. The maximum line length is main size of the flexbox's content box, constrained by the min and max main size constraints of the flexbox. If the main size depends on the flexbox's content, then:</p>
alexmog@4725 988
alexmog@4725 989 <ul>
alexmog@4725 990 <li>for ''min-content'', the maximum line length is the flexbox's minimum main size, constrained by the min and max main size constraints of the flexbox.</li>
alexmog@4725 991
alexmog@4725 992 <li>for ''max-content'', the maximum line length is infinity, constrained by the min and max main size constraints of the flexbox.</li>
alexmog@4725 993
alexmog@4725 994 <li>for ''fit-content'', the maximum line length is the greater of the flexbox's min size constraint and the smaller of the flexbox's max size constraint and the available space.</li>
alexmog@4725 995 </ul>
alexmog@4725 996 </li>
alexmog@4725 997
alexmog@4725 998 <li>Collect as many consecutive flexbox items as possible, starting from the first item, while keeping the sum of their main size smaller than the flexbox's available space. If a flexbox item is sized with a flexible length, then for the purpose of this step, clamp the item's size between its minimum and maximum main sizes. The items so collected form a single flexbox line.</li>
alexmog@4725 999
alexmog@4725 1000 <li>Repeat the previous step, starting each time from the first flexbox item not yet collected into a flexbox line, until all flexbox items have been collected into flexbox lines.</li>
alexmog@4725 1001 </ol>
alexmog@4725 1002 </li>
alexmog@4725 1003
alexmog@4725 1004 <li>Find the actual main size of the flexbox. If the flexbox's main size doesn't rely on its contents, its actual main size is calculated per the appropriate rules. Otherwise, its main size is the length of its longest line, calculated by summing the main sizes of the margin boxes of each flexbox item in the line, constrained by the flexbox's min and max main size constraints.
alexmog@4725 1005 If any margins are set to &#39;auto&#39;, consider them to be set to zero until
alexmog@4725 1006 resolved in a separate step.</li>
alexmog@4725 1007
alexmog@4725 1008 <li>For each flexbox line,
alexmog@4725 1009 <ol>
alexmog@4725 1010 <li><i>Resolve the flexible lengths</i> of the items contained within it. All flexbox items now have a final main size. Update each item's hypothetical cross size based on this main size.</li>
alexmog@4725 1011
alexmog@4725 1012 <li>Calculate the leftover free-space by subtracting the sum of the
alexmog@4725 1013 margin-box main sizes of the items on the line from the main size of the flexbox's content box.</li>
alexmog@4725 1014 <li>Resolve &#39;auto&#39; margins on main axis:<ol>
alexmog@4725 1015 <li>If leftover free-space is positive and any items on this
alexmog@4725 1016 line have at least one main-axis margin set to &#39;auto&#39;,
alexmog@4725 1017 distribute the leftover free-space equally to these margins.</li>
alexmog@4725 1018 <li>If leftover free-space is negative, any main-axis &#39;auto&#39;
alexmog@4725 1019 margins on items in this line are set to zero.</li>
alexmog@4725 1020 </ol>
alexmog@4725 1021 </li>
alexmog@4725 1022 <li>
alexmog@4725 1023 Align the items along the main axis per 'flex-pack'.
alexmog@4725 1024 </li>
alexmog@4725 1025 </ol>
alexmog@4725 1026 </li>
alexmog@4725 1027
alexmog@4725 1028 <li>Calculate the cross size of each flexbox line. For each flexbox
alexmog@4725 1029 line:
alexmog@4725 1030 <ol>
alexmog@4725 1031 <li>If the flexbox is single-line and has a definite cross size, the single flexbox line's cross size is the cross size of the flexbox's content box. End this step of the algorithm.</li>
alexmog@4725 1032
alexmog@4725 1033 <li>If main axis is parallel to inline axis, collect all the flexbox items with a 'flex-item-align' of 'baseline'. Find the maximum of the distances from their baseline to the cross-start edge of their margin box, and the maximum of the distances from their baseline to the cross-end edge of their margin box. Sum these two values.</li>
alexmog@4725 1034
alexmog@4725 1035 <li>For remaining flexbox items, find the maximum of the cross sizes of their margin boxes.
alexmog@4725 1036
alexmog@4725 1037 <li>The cross size of the flexbox line is the larger of the numbers found in the previous two steps.</li>
alexmog@4725 1038 <li>If the flexbox is multi-line, has a definite cross size,
alexmog@4725 1039 &#39;flex-line-pack&#39; is set to &#39;stretch&#39; and sum of cross size of
alexmog@4725 1040 all lines is less than cross size of content box, increase cross
alexmog@4725 1041 size of each line by equal amount to exactly match the cross
alexmog@4725 1042 size of content box.</li>
alexmog@4725 1043 </ol>
alexmog@4725 1044 </li>
alexmog@4725 1045
alexmog@4725 1046 <li>If the flexbox doesn't have a definite cross size, the cross size of its content box is the sum of the cross sizes of all of its lines.</li>
alexmog@4725 1047
alexmog@4725 1048 <li>Determine the final cross size of each flexbox item. For each flexbox item, if it has ''flex-item-align:stretch'', its final cross size is
alexmog@4725 1049 set so that its margin-box cross size is equal to cross-size of its flexbox line. For all other flexbox items, its final cross size is its hypothetical cross size.
alexmog@4725 1050 If the result conflicts with &#39;min-width&#39;, &#39;max-width&#39;, &#39;min-height&#39; or
alexmog@4725 1051 &#39;max-height&#39;, correct the result to comply the restrictions.</li>
alexmog@4725 1052 <p class="issue">'auto' height must only grow, not shrink here</p>
alexmog@4725 1053
alexmog@4725 1054 <li>Resolve &#39;auto&#39; margins on cross axis. For each flexbox item, if its
alexmog@4725 1055 margin box cross size is smaller than cross size of its line and it has
alexmog@4725 1056 any margins in cross direction set to &#39;auto&#39;, distribute the difference
alexmog@4725 1057 equally to the auto margins. </li>
alexmog@4725 1058 <li>For each flexbox line, align the flexbox items per 'flex-item-align'.</li>
alexmog@4725 1059
alexmog@4725 1060 <li>Align the flexbox lines per 'flex-line-pack'. The leftover free-space is calculated by subtracting the sum of the flexbox line's cross sizes from the cross size of the flexbox's content box.</li>
alexmog@4725 1061 <li>Layout all items again in their final size and position.
alexmog@4725 1062 Implementations can determine when this step is needed and how it can be
alexmog@4725 1063 optimized, but for precise results it has to be assumed that this step
alexmog@4725 1064 is performed, because the layout of each item&#39;s content may change when
alexmog@4725 1065 ea</li>
alexmog@4725 1066 </ol>
alexmog@4725 1067
alexmog@4725 1068 <p>To <dfn>resolve the flexible lengths</dfn> of the items within a flexbox line:</p>
alexmog@4725 1069
alexmog@4725 1070 <ol>
alexmog@4725 1071 <li>
alexmog@4725 1072 Determine sign of flexibility
alexmog@4725 1073
alexmog@4725 1074 <ol>
alexmog@4725 1075 <li>Add sizes of all items, <i>adjusted for min/max</i>.
alexmog@4725 1076
alexmog@4725 1077 <li>If sum of preferred sizes is less than available space, use positive flexibility, otherwise use negative flexibility.</li>
alexmog@4725 1078 </ol>
alexmog@4725 1079
alexmog@4725 1080 <p>for the rest of the algorithm use flexibility with the sign determined in this step</p>
alexmog@4725 1081 </li>
alexmog@4725 1082
alexmog@4725 1083 <li>Reset all flexible sizes to their preferred size</li>
alexmog@4725 1084
alexmog@4725 1085 <li>Find free space by subtracting sum of item sizes from available space.</li>
alexmog@4725 1086
alexmog@4725 1087 <li>
alexmog@4725 1088 Distribute free space proportional to flex:
alexmog@4725 1089
alexmog@4725 1090 <ol>
alexmog@4725 1091 <li>If the free space is positive, but step 1 chose negative flexibility, do nothing</li>
alexmog@4725 1092
alexmog@4725 1093 <li>If the free space is negative, but step 1 chose positive flexibility, do nothing</li>
alexmog@4725 1094
alexmog@4725 1095 <li>Add a portion of free space to each flexible item,
alexmog@4725 1096 proportional to item's flexibility</li>
alexmog@4725 1097 </ol>
alexmog@4725 1098 </li>
alexmog@4725 1099
alexmog@4725 1100 <li>
alexmog@4725 1101 Fix min/max violations:
alexmog@4725 1102
alexmog@4725 1103 <ol>
alexmog@4725 1104 <li>Adjust each flexible item for min/max. </li>
alexmog@4725 1105
alexmog@4725 1106 <li>If the size has changed, it is a violation. </li>
alexmog@4725 1107
alexmog@4725 1108 <li>The violation may be positive (min violation) or negative (max violation). Accumulate the difference.</li>
alexmog@4725 1109 </ol>
alexmog@4725 1110 </li>
alexmog@4725 1111
alexmog@4725 1112 <li>
alexmog@4725 1113 If the sum of all violations is:
alexmog@4725 1114
alexmog@4725 1115 <dl>
alexmog@4725 1116 <dt>Zero</dt>
alexmog@4725 1117 <dd>Exit the algorithm.</dd>
alexmog@4725 1118
alexmog@4725 1119 <dt>Positive</dt>
alexmog@4725 1120 <dd>Freeze items with max violations, and return to step 2.</dd>
alexmog@4725 1121
alexmog@4725 1122 <dt>Negative</dt>
alexmog@4725 1123 <dd>Freeze items with min violations, and return to step 2.</dd>
alexmog@4725 1124 </dl>
alexmog@4725 1125 </li>
alexmog@4725 1126 </ol>
alexmog@4725 1127
alexmog@4725 1128 <h2 id="pagination">
alexmog@4725 1129 Page breaks in flexbox</h2>
alexmog@4725 1130
alexmog@4725 1131 <p>Flexboxes can break across pages between items, between lines of items (in multi-line mode) and inside items, as long as 'break-' property allow that. All 'break-' properties are supported on flexbox, on flexbox items and inside flexbox items.</p>
alexmog@4725 1132
alexmog@4725 1133 <p>The following breaking rules refer to fragmentation container as “page”. The same rules apply to any other fragmenters. Change “page” to the appropriate fragmenter type as needed.</p>
alexmog@4725 1134
alexmog@4725 1135 <p>Breaks in and around flexbox are determined as follows:</p>
alexmog@4725 1136
alexmog@4725 1137 <ol>
alexmog@4725 1138 <li> Break-before, break-after, break-inside properties on flexbox itself have effect as normal. If breaks inside flexbox are allowed, break points are determined using following rules.</li>
alexmog@4725 1139
alexmog@4725 1140 <li>When flexbox is continued after a break, flexbox’s available space in block direction is reduced by space consumed in previous pages. Consumed space before page break is:
alexmog@4725 1141
alexmog@4725 1142 <ol>
alexmog@4725 1143 <li>If flexbox starts on that page: the distance between start of content box of the flexbox and the end of available space</li>
alexmog@4725 1144
alexmog@4725 1145 <li>If flexbox continues from previous page: the size of available space.</li>
alexmog@4725 1146 </ol>
alexmog@4725 1147
alexmog@4725 1148 <p>If as a result of this adjustment block-direction size of flexbox becomes negative, it is set to zero.</p>
alexmog@4725 1149 </li>
alexmog@4725 1150
alexmog@4725 1151 <li>
alexmog@4725 1152 <dfn>Forced breaks on flexbox items</dfn>
alexmog@4725 1153
alexmog@4725 1154 <ol>
alexmog@4725 1155 <li>In a row-direction single-line flexbox, breaks before and after items apply to the flexbox</li>
alexmog@4725 1156 <p class="issue">"break-inside:avoid" in single-line horizontal should probably be applied to flexbox too.</p>
alexmog@4725 1157
alexmog@4725 1158 <li>In column-direction single-line flexbox and all multi-line flexboxes:
alexmog@4725 1159
alexmog@4725 1160 <ol>
alexmog@4725 1161 <li>Forced break before the first item is applied to the flexbox</li>
alexmog@4725 1162
alexmog@4725 1163 <li>Forced break after the last item is applied to the flexbox</li>
alexmog@4725 1164
alexmog@4725 1165 <li>Forced break before or after any other item terminates the set of items to be laid out on this page</li>
alexmog@4725 1166 </ol>
alexmog@4725 1167 </li>
alexmog@4725 1168 </ol>
alexmog@4725 1169
alexmog@4725 1170 </li>
alexmog@4725 1171
alexmog@4725 1172 <li>When necessary, a <dfn>break inside a flexbox item is considered</dfn> as follows:
alexmog@4725 1173
alexmog@4725 1174 <ol>
alexmog@4725 1175 <li>If the item has “break-inside:avoid”, it is pushed to the next page</li>
alexmog@4725 1176
alexmog@4725 1177 <li>Otherwise, it may be broken, according to breaking rules and algorithms applicable to its display type. </li>
alexmog@4725 1178
alexmog@4726 1179 <li>Forced breaks inside flexbox item content are handled normally, but in row-direction flexbox they don&#39;t affect layout of sibling
alexmog@4726 1180 flexbox items (e.g. a forced break inside an item doesn&#39;t prevent its next sibling from appearing on the same page)</li>
alexmog@4725 1181 </ol>
alexmog@4725 1182 </li>
alexmog@4725 1183
alexmog@4725 1184 <li>
alexmog@4725 1185 <b>Column-direction flexbox: single-line</b>
alexmog@4725 1186
alexmog@4725 1187 <ol>
alexmog@4725 1188 <li>
alexmog@4725 1189 <p>If flexbox main-axis size is definite, flexbox algorithm must be run first, without constraints of available space on page and using all content of the flexbox. Otherwise items use the preferred size, adjusted for min/max.</p>
alexmog@4725 1190
alexmog@4725 1191 <p>If page size varies and flexbox size depends on page size, this step has to be repeated on each page, again with the whole content of the flexbox.</p>
alexmog@4725 1192 </li>
alexmog@4725 1193
alexmog@4725 1194 <li>Set of items that will fit on current page is determined by adding main-axis sizes of items until total size exceeds
alexmog@4725 1195 available space or a forced break is encountered.</li>
alexmog@4725 1196
alexmog@4725 1197 <li>If border box of an item doesn’t fit in available space, a break inside the item is considered</li>
alexmog@4725 1198
alexmog@4725 1199 <li>
alexmog@4725 1200 <p>Items that fit on a page completely or partially are aligned according to ‘flex-pack’ property, independently from the rest of flexbox content.</p>
alexmog@4725 1201
alexmog@4725 1202 <p>Note that flexible lengths are not recalculated on each page, even if there is additional free space.</p>
alexmog@4725 1203 </li>
alexmog@4725 1204 </ol>
alexmog@4725 1205
alexmog@4725 1206 <p class="note">It is the intent of this spec that column-direction single-line flexbox paginates very
alexmog@4725 1207 similarly to block flow. As a test of the intent, a flexbox with "flex-pack:start" and no flexible items should paginate identically to a block with non-floating children with same content, same used size and same used margins. This rule is simplified and not normative, but if there is any difference it should be noted here.</p>
alexmog@4725 1208 </li>
alexmog@4725 1209
alexmog@4725 1210 <li>
alexmog@4725 1211 <b>Column-direction flexbox: multi-line</b>
alexmog@4725 1212
alexmog@4725 1213 <ol>
alexmog@4725 1214 <li>Items are collected in lines and laid out as usual, but in available space on current page.</li>
alexmog@4725 1215
alexmog@4725 1216 <li>If border box of an item doesn’t fit on main-axis and it is
alexmog@4725 1217 the only item in its line:
alexmog@4725 1218 <ol>
alexmog@4725 1219 <li>If the flexbox is not at the top of the page, it is moved to the next page.</li>
alexmog@4725 1220
alexmog@4725 1221 <li>If the flexbox is already at the top of the page, the item may produce overflow. If 'overflow' property of the flexbox is set to 'visible', it is paginated using same rules as visible overflow of blocks in normal flow.
alexmog@4725 1222
alexmog@4725 1223 <p class="note">After the break, continuation of overflow items may overlap with other items and/or content after the flexbox. It is undesirable but there is no good resolution for this spacial conflict and this outcome is similar to effect of "overflow:visible" elsewhere.</p>
alexmog@4725 1224 </li>
alexmog@4725 1225 </ol>
alexmog@4725 1226 </li>
alexmog@4725 1227 </ol>
alexmog@4725 1228 </li>
alexmog@4725 1229 <li>Breaks inside items (forced or unforced) are not allowed</li>
alexmog@4725 1230 </ol>
alexmog@4725 1231 </li>
alexmog@4725 1232
alexmog@4725 1233 <li>
alexmog@4725 1234 <b>Row-direction flexbox: single-line</b>
alexmog@4725 1235
alexmog@4725 1236 <ol>
alexmog@4725 1237 <li>
alexmog@4725 1238 <p>Main-axis space distribution in each line is done based on complete content of the flexbox and without space constraint in block direction.</p>
alexmog@4725 1239
alexmog@4725 1240 <p>If page size varies and flexbox size depends on page size, this step needs to be repeated on each page.</p>
alexmog@4725 1241 </li>
alexmog@4725 1242
alexmog@4725 1243 <li>Items are sized and positioned as usual, but in block-direction available space of min(remaining available space in flexbox, remaining space on the page).</li>
alexmog@4725 1244
alexmog@4725 1245 <li>Any items with baseline alignment must be aligned before considering breaks inside items.</li>
alexmog@4725 1246
alexmog@4725 1247 <li>If border box of an item doesn’t fit in current page, a break inside the item is considered</li>
alexmog@4725 1248
alexmog@4725 1249 <li>Items that have fit completely on a previous page and items that are pushed to next page don’t have any rendering, leaving empty space as needed.</li>
alexmog@4725 1250
alexmog@4725 1251 <li>Items that fit completely or partially on current page are aligned on cross-axis:
alexmog@4725 1252
alexmog@4725 1253 <ol>
alexmog@4725 1254 <li>For the purposes of cross-axis alignment, minimum of remaining available space in flexbox and available space at current page is used.</li>
alexmog@4725 1255
alexmog@4725 1256 <li>If an item is broken in the previous step and its alignment is not baseline, its cross-axis size is set to available space. If item alignment is baseline, its cross-axis size is adjusted so that it extends to exactly the end of available space.</li>
alexmog@4725 1257 </ol>
alexmog@4725 1258 </li>
alexmog@4725 1259 </ol>
alexmog@4725 1260 </li>
alexmog@4725 1261
alexmog@4725 1262 <li>
alexmog@4725 1263 <b>Row-direction flexbox:multi-line</b>
alexmog@4725 1264
alexmog@4725 1265 <ol>
alexmog@4725 1266 <li>Collect items into lines and determine line heights:
alexmog@4725 1267
alexmog@4725 1268 <ol>
alexmog@4725 1269 <li>
alexmog@4725 1270 <p>If 'flex-line-pack' is 'stretch' and flexbox size in block direction is definite, layout of the complete flexbox has to be done first to determine line heights. Layout is done as usual for non-paginated case, but accounting for forced breaks.</p>
alexmog@4725 1271
alexmog@4725 1272 <p>If page size varies, this step may have to be redone, again with complete content; special consideration should be to be given to line breaks to ensure that item at the start of current page is also at the start of a line in this hypothetical layout. This specification currently doesn't define how exactly to achieve that.</p>
alexmog@4725 1273 </li>
alexmog@4725 1274
alexmog@4725 1275 <li>Otherwise, items are collected into lines and each line is laid out as a single-line flexbox to determine block-direction size of each line.</li>
alexmog@4725 1276 </ol>
alexmog@4725 1277 </li>
alexmog@4725 1278
alexmog@4725 1279 <li>Lines are added one at a time, until out of available space or a forced break is encountered</li>
alexmog@4725 1280
alexmog@4725 1281 <li>Breaks inside items (forced or unforced) are not allowed.</li>
alexmog@4725 1282 <li>If the first flexbox line on a page doesn&#39;t fit in
alexmog@4725 1283 cross-axis,
alexmog@4725 1284 <ol>
alexmog@4725 1285 <li>If the flexbox is not at the top of the page, it is moved to the next page.</li>
alexmog@4725 1286 <li>If the flexbox is already at the top of the page, the item may produce overflow. If 'overflow' property of the flexbox is set to 'visible', it is paginated using same rules as visible overflow of blocks in normal flow.</li>
alexmog@4725 1287 </ol>
alexmog@4725 1288 </li>
alexmog@4725 1289
alexmog@4725 1290 <li>If size of flexbox in inline direction is not definite, multi-line layout algorithm is run using the set of items
alexmog@4725 1291 that have fit on the current page.</li>
alexmog@4725 1292
alexmog@4725 1293 <li>Line packing is done on each page, with content on the page</li>
alexmog@4725 1294 <p class="issue">TODO: combine breaking algorithms for multiline in both directions. If breaks inside items are not allowed the algorithm is almost same.</p>
alexmog@4725 1295 </ol>
alexmog@4725 1296 </li>
alexmog@4725 1297 </ol>
alexmog@4725 1298
alexmog@4725 1299 <h2 id="conformance">
alexmog@4725 1300 Conformance</h2>
alexmog@4725 1301
alexmog@4725 1302 <h3 id="conventions">
alexmog@4725 1303 Document conventions</h3>
alexmog@4725 1304
alexmog@4725 1305 <p>Conformance requirements are expressed with a combination of
alexmog@4725 1306 descriptive assertions and RFC 2119 terminology. The key words “MUST”,
alexmog@4725 1307 “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
alexmog@4725 1308 “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this
alexmog@4725 1309 document are to be interpreted as described in RFC 2119.
alexmog@4725 1310 However, for readability, these words do not appear in all uppercase
alexmog@4725 1311 letters in this specification.
alexmog@4725 1312
alexmog@4725 1313 <p>All of the text of this specification is normative except sections
alexmog@4725 1314 explicitly marked as non-normative, examples, and notes. [[!RFC2119]]</p>
alexmog@4725 1315
alexmog@4725 1316 <p>Examples in this specification are introduced with the words “for example”
alexmog@4725 1317 or are set apart from the normative text with <code>class="example"</code>,
alexmog@4725 1318 like this:
alexmog@4725 1319
alexmog@4725 1320 <div class="example">
alexmog@4725 1321 <p>This is an example of an informative example.</p>
alexmog@4725 1322 </div>
alexmog@4725 1323
alexmog@4725 1324 <p>Informative notes begin with the word “Note” and are set apart from the
alexmog@4725 1325 normative text with <code>class="note"</code>, like this:
alexmog@4725 1326
alexmog@4725 1327 <p class="note">Note, this is an informative note.</p>
alexmog@4725 1328
alexmog@4725 1329 <h3 id="conformance-classes">
alexmog@4725 1330 Conformance classes</h3>
alexmog@4725 1331
alexmog@4725 1332 <p>Conformance to CSS Flexbox Layout Module
alexmog@4725 1333 is defined for three conformance classes:
alexmog@4725 1334 <dl>
alexmog@4725 1335 <dt><dfn title="style sheet!!as conformance class">style sheet</dfn>
alexmog@4725 1336 <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS
alexmog@4725 1337 style sheet</a>.
alexmog@4725 1338 <dt><dfn>renderer</dfn></dt>
alexmog@4725 1339 <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a>
alexmog@4725 1340 that interprets the semantics of a style sheet and renders
alexmog@4725 1341 documents that use them.
alexmog@4725 1342 <dt><dfn id="authoring-tool">authoring tool</dfn></dt>
alexmog@4725 1343 <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a>
alexmog@4725 1344 that writes a style sheet.
alexmog@4725 1345 </dl>
alexmog@4725 1346
alexmog@4725 1347 <p>A style sheet is conformant to CSS Flexbox Layout Module
alexmog@4725 1348 if all of its statements that use syntax defined in this module are valid
alexmog@4725 1349 according to the generic CSS grammar and the individual grammars of each
alexmog@4725 1350 feature defined in this module.
alexmog@4725 1351
alexmog@4725 1352 <p>A renderer is conformant to CSS Flexbox Layout Module
alexmog@4725 1353 if, in addition to interpreting the style sheet as defined by the
alexmog@4725 1354 appropriate specifications, it supports all the features defined
alexmog@4725 1355 by CSS Flexbox Layout Module by parsing them correctly
alexmog@4725 1356 and rendering the document accordingly. However, the inability of a
alexmog@4725 1357 UA to correctly render a document due to limitations of the device
alexmog@4725 1358 does not make the UA non-conformant. (For example, a UA is not
alexmog@4725 1359 required to render color on a monochrome monitor.)
alexmog@4725 1360
alexmog@4725 1361 <p>An authoring tool is conformant to CSS Flexbox Layout Module
alexmog@4725 1362 if it writes style sheets that are syntactically correct according to the
alexmog@4725 1363 generic CSS grammar and the individual grammars of each feature in
alexmog@4725 1364 this module, and meet all other conformance requirements of style sheets
alexmog@4725 1365 as described in this module.
alexmog@4725 1366
alexmog@4725 1367 <h3 id="partial">
alexmog@4725 1368 Partial implementations</h3>
alexmog@4725 1369
alexmog@4725 1370 <p>So that authors can exploit the forward-compatible parsing rules to
alexmog@4725 1371 assign fallback values, CSS renderers <strong>must</strong>
alexmog@4725 1372 treat as invalid (and <a href="http://www.w3.org/TR/CSS21/conform.html#ignore">ignore
alexmog@4725 1373 as appropriate</a>) any at-rules, properties, property values, keywords,
alexmog@4725 1374 and other syntactic constructs for which they have no usable level of
alexmog@4725 1375 support. In particular, user agents <strong>must not</strong> selectively
alexmog@4725 1376 ignore unsupported component values and honor supported values in a single
alexmog@4725 1377 multi-value property declaration: if any value is considered invalid
alexmog@4725 1378 (as unsupported values must be), CSS requires that the entire declaration
alexmog@4725 1379 be ignored.</p>
alexmog@4725 1380
alexmog@4725 1381 <h3 id="experimental">
alexmog@4725 1382 Experimental implementations</h3>
alexmog@4725 1383
alexmog@4725 1384 <p>To avoid clashes with future CSS features, the CSS2.1 specification
alexmog@4725 1385 reserves a <a href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords">prefixed
alexmog@4725 1386 syntax</a> for proprietary and experimental extensions to CSS.
alexmog@4725 1387
alexmog@4725 1388 <p>Prior to a specification reaching the Candidate Recommendation stage
alexmog@4725 1389 in the W3C process, all implementations of a CSS feature are considered
alexmog@4725 1390 experimental. The CSS Working Group recommends that implementations
alexmog@4725 1391 use a vendor-prefixed syntax for such features, including those in
alexmog@4725 1392 W3C Working Drafts. This avoids incompatibilities with future changes
alexmog@4725 1393 in the draft.
alexmog@4725 1394 </p>
alexmog@4725 1395
alexmog@4725 1396 <h3 id="testing">
alexmog@4725 1397 Non-experimental implementations</h3>
alexmog@4725 1398
alexmog@4725 1399 <p>Once a specification reaches the Candidate Recommendation stage,
alexmog@4725 1400 non-experimental implementations are possible, and implementers should
alexmog@4725 1401 release an unprefixed implementation of any CR-level feature they
alexmog@4725 1402 can demonstrate to be correctly implemented according to spec.
alexmog@4725 1403
alexmog@4725 1404 <p>To establish and maintain the interoperability of CSS across
alexmog@4725 1405 implementations, the CSS Working Group requests that non-experimental
alexmog@4725 1406 CSS renderers submit an implementation report (and, if necessary, the
alexmog@4725 1407 testcases used for that implementation report) to the W3C before
alexmog@4725 1408 releasing an unprefixed implementation of any CSS features. Testcases
alexmog@4725 1409 submitted to W3C are subject to review and correction by the CSS
alexmog@4725 1410 Working Group.
alexmog@4725 1411
alexmog@4725 1412 <p>Further information on submitting testcases and implementation reports
alexmog@4725 1413 can be found from on the CSS Working Group's website at
alexmog@4725 1414 <a href="http://www.w3.org/Style/CSS/Test/">http://www.w3.org/Style/CSS/Test/</a>.
alexmog@4725 1415 Questions should be directed to the
alexmog@4725 1416 <a href="http://lists.w3.org/Archives/Public/public-css-testsuite">public-css-testsuite@w3.org</a>
alexmog@4725 1417 mailing list.
alexmog@4725 1418
alexmog@4725 1419 <h3 id="cr-exit-criteria">
alexmog@4725 1420 CR exit criteria</h3>
alexmog@4725 1421
alexmog@4725 1422 <p>
alexmog@4725 1423 For this specification to be advanced to Proposed Recommendation,
alexmog@4725 1424 there must be at least two independent, interoperable implementations
alexmog@4725 1425 of each feature. Each feature may be implemented by a different set of
alexmog@4725 1426 products, there is no requirement that all features be implemented by
alexmog@4725 1427 a single product. For the purposes of this criterion, we define the
alexmog@4725 1428 following terms:
alexmog@4725 1429
alexmog@4725 1430 <dl>
alexmog@4725 1431 <dt>independent <dd>each implementation must be developed by a
alexmog@4725 1432 different party and cannot share, reuse, or derive from code
alexmog@4725 1433 used by another qualifying implementation. Sections of code that
alexmog@4725 1434 have no bearing on the implementation of this specification are
alexmog@4725 1435 exempt from this requirement.
alexmog@4725 1436
alexmog@4725 1437 <dt>interoperable <dd>passing the respective test case(s) in the
alexmog@4725 1438 official CSS test suite, or, if the implementation is not a Web
alexmog@4725 1439 browser, an equivalent test. Every relevant test in the test
alexmog@4725 1440 suite should have an equivalent test created if such a user
alexmog@4725 1441 agent (UA) is to be used to claim interoperability. In addition
alexmog@4725 1442 if such a UA is to be used to claim interoperability, then there
alexmog@4725 1443 must one or more additional UAs which can also pass those
alexmog@4725 1444 equivalent tests in the same way for the purpose of
alexmog@4725 1445 interoperability. The equivalent tests must be made publicly
alexmog@4725 1446 available for the purposes of peer review.
alexmog@4725 1447
alexmog@4725 1448 <dt>implementation <dd>a user agent which:
alexmog@4725 1449
alexmog@4725 1450 <ol class=inline>
alexmog@4725 1451 <li>implements the specification.
alexmog@4725 1452
alexmog@4725 1453 <li>is available to the general public. The implementation may
alexmog@4725 1454 be a shipping product or other publicly available version
alexmog@4725 1455 (i.e., beta version, preview release, or “nightly build”).
alexmog@4725 1456 Non-shipping product releases must have implemented the
alexmog@4725 1457 feature(s) for a period of at least one month in order to
alexmog@4725 1458 demonstrate stability.
alexmog@4725 1459
alexmog@4725 1460 <li>is not experimental (i.e., a version specifically designed
alexmog@4725 1461 to pass the test suite and is not intended for normal usage
alexmog@4725 1462 going forward).
alexmog@4725 1463 </ol>
alexmog@4725 1464 </dl>
alexmog@4725 1465
alexmog@4725 1466 <p>The specification will remain Candidate Recommendation for at least
alexmog@4725 1467 six months.
alexmog@4725 1468
alexmog@4725 1469
alexmog@4725 1470 <hr title="Separator from footer">
alexmog@4725 1471
alexmog@4725 1472 <h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
alexmog@4725 1473
alexmog@4725 1474 <p>Thanks for feedback and contributions to
alexmog@4725 1475
alexmog@4725 1476 Andrew Fedoniouk,
alexmog@4725 1477 Arron Eicholz,
alexmog@4725 1478 James Elmore,
alexmog@4725 1479 Ben Horst,
alexmog@4725 1480 Boris Zbarsky,
alexmog@4725 1481 Brad Kemper,
alexmog@4725 1482 Brian Heuston,
alexmog@4725 1483 Christian Stockwell,
alexmog@4725 1484 Christoph Päper,
alexmog@4725 1485 Daniel Holbert,
alexmog@4725 1486 Erik Anderson,
alexmog@4725 1487 Eugene Veselov,
alexmog@4725 1488 Fantasai,
alexmog@4725 1489 John Jansen,
alexmog@4725 1490 Markus Mielke,
alexmog@4725 1491 Ning Rogers,
alexmog@4725 1492 Ojan Vafai,
alexmog@4725 1493 Peter Salas,
alexmog@4725 1494 Phil Cupp,
alexmog@4725 1495 Robert O'Callahan,
alexmog@4725 1496 Rossen Atanassov,
alexmog@4725 1497 Shinichiro Hamaji,
alexmog@4725 1498 Tony Chang.
alexmog@4725 1499
alexmog@4725 1500 </p>
alexmog@4725 1501
alexmog@4725 1502
alexmog@4725 1503 <h2 class="no-num" id="references">References</h2>
alexmog@4725 1504
alexmog@4725 1505 <h3 class="no-num" id="normative">Normative references</h3>
alexmog@4725 1506 <!--normative-->
alexmog@4725 1507
alexmog@4725 1508 <h3 class="no-num" id="informative">Other references</h3>
alexmog@4725 1509 <!--informative-->
alexmog@4725 1510
alexmog@4725 1511 <h2 id="property" class="no-num">Property index</h2>
alexmog@4725 1512 <!--properties-->
alexmog@4725 1513
alexmog@4725 1514 <h2 class="no-num" id="index">Index</h2>
alexmog@4725 1515 <!--index-->
alexmog@4725 1516
alexmog@4725 1517 </body></html>
alexmog@4725 1518 <!-- Keep this comment at the end of the file
alexmog@4725 1519 Local variables:
alexmog@4725 1520 mode: sgml
alexmog@4725 1521 sgml-declaration:"~/SGML/HTML4.decl"
alexmog@4725 1522 sgml-default-doctype-name:"html"
alexmog@4725 1523 sgml-minimize-attributes:t
alexmog@4725 1524 sgml-nofill-elements:("pre" "style" "br")
alexmog@4725 1525 sgml-live-element-indicator:t
alexmog@4725 1526 sgml-omittag:nil
alexmog@4725 1527 sgml-shorttag:nil
alexmog@4725 1528 sgml-namecase-general:t
alexmog@4725 1529 sgml-general-insert-case:lower
alexmog@4725 1530 sgml-always-quote-attributes:t
alexmog@4725 1531 sgml-indent-step:nil
alexmog@4725 1532 sgml-indent-data:t
alexmog@4725 1533 sgml-parent-document:nil
alexmog@4725 1534 sgml-exposed-tags:nil
alexmog@4725 1535 sgml-local-catalogs:nil
alexmog@4725 1536 sgml-local-ecat-files:nil
alexmog@4725 1537 End:
jackalmage@3431 1538 -->

mercurial