css3-flexbox/Overview.src.html

Sun, 11 Mar 2012 16:37:02 -0700

author
Alex Mogilevsky <alexmog@microsoft.com>
date
Sun, 11 Mar 2012 16:37:02 -0700
changeset 4724
c515c530ea37
parent 4708
166bd5c52fbd
child 4725
d3362b8a88c8
permissions
-rw-r--r--

fix typos

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

mercurial