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.
Status of this document
This section describes the status of this document at the time of
its publication. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical report
can be found in the W3C technical reports
index at http://www.w3.org/TR/.
Publication as a Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
The (archived) public
mailing list www-style@w3.org (see
instructions) is preferred
for discussion of this specification. When sending e-mail, please put the
text “css3-flexbox” in the subject, preferably like this:
“[css3-flexbox] …summary of
comment…”
CSS 2.1 defined four layout modes — 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.
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.
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 multi-line, the flexbox items flow in two
dimensions, wrapping into separate lines in a fashion similar to how text
is wrapped into multiple lines.
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:
<ul>
<li><button><img src='new.svg' alt="New"></button></li>
<li><button><img src='upload.svg' alt="Upload"></button></li>
<li><button><img src='save.svg' alt="Save"></button></li>
<li><button><img src='trash.svg' alt="trash"></button></li>
</ul>
<style>
ul { display: flexbox; flex-pack: distribute; }
/* Irrelevant styling for this example removed. */
</style>
Example rendering of the above code snippet, at two
different flexbox widths.
1.1. Module interactions
This module extends the definition of the ‘display’ property.
1.2. Values
This specification follows the CSS property
definition conventions from [CSS21]. Value types not defined in
this specification are defined in CSS Level 2 Revision 1 [CSS21]. Other CSS
modules may expand the definitions of these value types: for example [CSS3COLOR],
when combined with this module, expands the definition of the
<color> value type as used in this specification.
In addition to the property-specific values listed in their definitions,
all properties defined in this specification also accept the ‘inherit’ keyword as their property value. For
readability it has not been repeated explicitly.
2. The Flexbox Box Model
An element with ‘display:flexbox’ or
‘display:inline-flexbox’ is a flexbox. Children of a flexbox are called flexbox
items and are laid out using the flexbox box model.
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.
An illustration of the various directions and sizing
terms used in this specification, respectively for ‘row’ and ‘column’
flexboxes.
The main axis of a flexbox is the axis on which
flexbox items are laid out along. The
flexbox items are ordered such that
they start on the main-start side of the flexbox,
and go toward the main-end side. A flexbox item's width or height, whichever
is in the main axis, is the item's main size. The flexbox
item's main size property is
either the ‘width’ or ‘height’ property, whichever is in the main axis.
The axis perpendicular to the main axis
is called the cross axis, and similarly has cross-start and cross-end
directions and sides defined. The width or height of a flexbox item, whichever is in the cross axis, is the item's cross size, and similarly the cross size property is whichever of
‘width’ or ‘height’ that is in the cross axis.
The contents of a flexbox can be easily and powerfully manipulated with
a handful of properties. Most significantly, flexbox items can "flex" their main size 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 flexbox items have finished
flexing, the items can be aligned, centered, or distributed with the
‘flex-pack’ property. Flexbox items can also be completely
rearranged within the flexbox with the ‘flex-order’ property.
In the cross axis, flexbox items can either "flex" to fill
the available space or be aligned within the space with the ‘flex-align’
property. If a flexbox is multi-line,
new lines are added in the cross-end
direction, and can similarly be aligned, centered, or distributed within
the flexbox with the ‘flex-line-pack’ property.
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’.
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 block flexbox
and the latter type as an inline flexbox.
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:
all of the ‘column-*’ properties in
the Multicol module have no effect on a flexbox.
‘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 flexbox items needs the computed value of
‘display’).
‘vertical-align’ has no effect
on the alignment of a flexbox item in the flexbox
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’.
A flexbox establishes a new flexbox
formatting context 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 flexbox items
establish a new formatting context for its contents.
4. Flexbox Items
Flexbox layout algorithm operates on flexbox
items, which are boxes that satisfy at least one of the following
criteria:
Immediate block-level children of flexbox
Atomic inline-level children of flexbox
Contiguous run of non-replaced inline children, wrapped into an
anonymous box
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
before a flexbox's contents are checked to see if it's necessary
to generate anonymous flexbox items.
In the future, other kinds of fixup such as ‘display:run-in’ or ‘display:ruby’ should also run before flexbox fixup.
Examples of flexbox items:
<div style="display:flexbox">
<!-- flexbox item: block-level child -->
<div id="item1">block</div>
<!-- not a flexbox item, because it's out-of-flow -->
<div id="not-an-item1.5" style="position: absolute;">block</div>
<!-- flexbox item: block-level child -->
<div id="item2" style="display:table">table</div>
<!-- flexbox item: anonymous table wrapped around table-cell -->
<div id="item3" style="display:table-cell">table-cell</div>
<!-- flexbox item: anonymous block around inline content -->
anonymous item 4
<!-- flexbox item: block-level child -->
<div id="item5">block</div>
<!-- flexbox item: anonymous block around inline content -->
anonymous item 6.1
<span id="item6.1">
text 6.2
<div id="not-an-item6.3">block</div>
text 6.4
</span>
<!-- flexbox item: block-level replaced element -->
<iframe id="item7"></iframe>
<!-- flexbox item: inline-level replaced element -->
<img id="item7" style="display:inline">
<!-- flexbox item: inline-level replaced element -->
<button id="item8">button</button>
<!-- flexbox item: inline-table -->
<div id="item9" style="display:inline-table">table</div>
<!-- flexbox item: floated inline, which changes to a block -->
<span id="item10" style="float: left;">span</span>
</div>
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 flexbox item. Similarly, the block element
"not-an-item1.5" is not a flexbox item, because it's absolutely
positioned and thus out of flow.
4.1. Absolutely
Positioned Flexbox Children
Absolutely positioned children of a flexbox are not flexbox items, 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 their anonymous flexbox item wrapper boxes.
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.
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.
5. Multi-line Flexbox
A flexbox can be either single-line or
multi-line, depending on the ‘flex-wrap’
property. A single-line flexbox lays out all of
its children in a single line, even if that would cause the flexbox to
overflow its bounds. A multi-line flexbox breaks
its flexbox items 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 flexbox item, unless the flexbox
itself is completely empty.
When additional lines are created, they are stacked in the flexbox in
the cross axis. 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 main size of a line is the same as the main size of the flexbox's content box. The
cross size of a line depends on whether
the flexbox is single-line or multi-line: the cross size of the sole line in a single-line flexbox is the same as the cross size of the flexbox's content box,
while the cross size of a line in a multi-line flexbox is the minimum size
necessary to contain the flexbox items
on the line, after aligning them with ‘flex-align’. The lines themselves are then
aligned within a flexbox with the ‘flex-line-pack’ property.
This example shows four buttons that do not fit horizontally.
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.
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.
If the box was resized, the buttons may rearrange onto different lines
as necessary.
If the style rules in the example above were changed to the following:
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.
6. Ordering and
Orientation
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.
6.1. Flexbox Flow
Direction: the ‘flex-direction’ property
The ‘flex-direction’ property specifies how flexbox items are placed in the flexbox,
by setting the direction of the flexbox's main
axis. This affects the direction that flexbox items are laid out
in, and the meaning of the ‘flex-pack’ property.
row
The flexbox's main axis has the same
orientation as the inline axis of the current writing mode (the direction
that text is laid out in). The main-start and main-end directions are equivalent to the
"start" and "end" directions, respectively, of the current writing mode.
The flexbox's main axis has the same
orientation as the block axis of the current writing mode (the direction
that blocks are laid out in). The main-start and main-end directions are equivalent to the
"before" and "after" directions, respectively, of the current writing
mode.
The flexbox is single-line. The cross-start direction is equivalent to
either the "start" or "before" direction of the current writing mode,
whichever is in the cross-axis, and the cross-end direction is the opposite
direction of cross-start.
wrap
The flexbox is multi-line. The cross-start direction is equivalent to
either the "start" or "before" direction of the current writing mode,
whichever is in the cross-axis, and the cross-end direction is the opposite
direction of cross-start.
div { flex-flow: row; }
/* Initial value. Main axis is
inline, no wrap. */
div { flex-flow: column wrap; }
/* Main axis is block-direction and lines
wrap in the inline direction. For an
English page, the main axis is top-to-bottom
and lines wrap to the right. */
div { writing-mode: vertical-rl;
flex-flow: column wrap-reverse; }
/* Main axis is block direction (right to
left). New lines wrap upwards. */
Flexbox items 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.
Ordinal groups control the order in which flexbox items 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.
The following figure shows a simple tabbed interface, where the tab for
the active pane is always in front:
This could be implemented with the following CSS (showing only the
flexbox-relevant code):
.tabs {
display: flexbox;
}
.tabs > .current {
flex-order: -1; /* Lower than the default of 0 */
}
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:
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:
@media all and (max-width: 600px) {
/* Too narrow to support three columns */
#main { flex-flow: column; }
#main > article, #main > nav, #main > aside {
/* Return them to document order */
flex-order: 0; width: auto;
}
}
(Further use of multiline flexboxes to achieve even more
intelligent wrapping left as an exercise for the reader.)
The defining aspect of flexbox layout is the ability to make the flexbox items "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.
The ‘flex’
property specifies the parameters of a flexible
length: the positive and negative flexibility, and the preferred size.
<pos-flex> and <neg-flex> are
non-negative <number>s. The <pos-flex>
component sets the positive
flexibility; if omitted, the positive flexibility defaults to
‘1’. The <neg-flex>
component sets the negative
flexibility; if omitted, it defaults to ‘0’.
The <preferred-size> component sets the preferred size.
It can be set to any value that would be valid in the ‘width’ or ‘height’ property, except values that are not
applicable to a component value (of values defined in CSS2.1, only
'inherit' is not valid for <preferred-size>; in
the future other values may be introduced that are not applicable as
length component). 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.
If the <preferred-size> is ‘0’, it must 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.
The keyword ‘none’ is equivalent
to "0 0 auto".
A ‘<flex>’ value is
transitionable, by transitioning the preferred size, positive flexibility, and negative flexibility
independently. ‘<flex>’ can also
transition to and from a <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.
Flexibility allows elements to respond directly to the available space,
optionally taking into account size of content:
<!DOCTYPE html>
<style>
div { display:flexbox; outline:1px solid silver; }
p { flex:1 auto; margin:1em; background:gold; }
</style>
<div>
<p>"flexing"</p>
<p>allows the items to get bigger</p>
<p>or</p>
<p>smaller</p>
</div>
8. Alignment
After a flexbox's contents have finished their flexing and dimensions of
margin boxes of all flexbox items are finalized, they can be aligned in
both the main axis with ‘flex-pack’ and
the cross axis 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.
The ‘flex-pack’ property aligns flexbox items in the main axis of the current line of the flexbox.
This is done after any flexible lengths and any auto
margins have been resolved. Typically it helps distribute extra free space
leftover when either all the flexbox
items 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.
start
Flexbox items are packed toward the
start of the line. The main-start margin
edge of the first flexbox item on the
line is placed flush with the main-start
edge of the line, and each subsequent flexbox
item is placed flush with the preceding item.
end
Flexbox items are packed toward the
end of the line. The main-end margin edge
of the last flexbox item is placed
flush with the main-end edge of the line,
and each preceding flexbox item is
placed flush with the subsequent item.
center
Flexbox items are packed toward the
center of the line. The flexbox items
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 main-start edge of the line and the first
item on the line and between the main-end
edge of the line and the last item on the line. (If the leftover
free-space is negative, the flexbox
items will overflow equally in both directions.)
justify
Flexbox items are evenly
distributed in the line. If the leftover free-space is negative or there
is only a single flexbox item on the
line, this value is identical to ‘start’.
Otherwise, the main-start margin edge of
the first flexbox item on the line is
placed flush with the main-start edge of
the line, the main-end margin edge of the
last flexbox item on the line is
placed flush with the main-end edge of the
line, and the remaining flexbox items
on the line are distributed so that the empty space between any two
adjacent items is the same.
distribute
Flexbox items 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 flexbox item on the line, this value is
identical to ‘center’. Otherwise, the flexbox items on the line are distributed
such that the empty space between any two adjacent flexbox items on the line is the same,
and the empty space before the first and after the last flexbox items on the line are half the
size of the other empty spaces.
An illustration of the five ‘flex-pack’
keywords and their effects on a flexbox with three colored items.
‘auto’ computes to parent's
‘flex-align’; otherwise as specified
Media:
visual
Animatable:
no
Flexbox items can be aligned in the
cross axis 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 items, including anonymous flexbox items. ‘flex-item-align’ allows this default
alignment to be overridden for individual flexbox items (for anonymous flexbox
items, ‘flex-item-align’ always matches the value
of ‘flex-align’ on their associated flexbox).
The flexbox item's margin box is
centered in the cross axis within the
line. (If the cross size of the flexbox
is less than that of the flexbox item,
it will overflow equally in both directions.)
Otherwise, all flexbox items 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 cross-start margin edge is placed flush
against the cross-start edge of the
line.
stretch
If the cross size property
of the flexbox item is ‘auto’, it resolves to the length necessary to
make the cross size of the item's
margin box the same size as the line, while still respecting
‘min/max-width/height’ constraints as
normal.
Margins on flexbox items can be set to 'auto', with effect very
similar to auto margins in normal flow.
Through calculations of preferred sizes and flexible lengths, auto
margins are considered to be zero.
Immediately before pack and align steps, if there are
any auto margins on items in the direction of alignment and there is
positive free space, the free space is distributed equally to the auto
margins.
If free space was distributed to auto margins, the following pack or
align step has no effect.
Auto margins can be used for simple alignment or for fine control.
Note that auto margins work consistently in both dimensions, so a
simple markup like this
div { display:flexbox;
width:4em; height:4em; background:silver;
}
p { margin:auto; }
<div><p>OK</p></div>
The ‘flex-line-pack’ property aligns a
flexbox's lines within the flexbox when there is extra space in the cross axis, similar to how ‘flex-pack’ aligns
individual items within the main axis:
start
Lines are packed toward the start of the flexbox. The cross-start edge of the first line in the
flexbox is placed flush with the cross-start edge of the flexbox, and each
subsequent line is placed flush with the preceding line.
end
Lines are packed toward the end of the flexbox. The cross-end edge of the last line is placed
flush with the cross-end edge of the
flexbox, and each preceding line is placed flush with the subsequent
line.
center
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 cross-start content edge of the flexbox
and the first line in the flexbox and between the cross-end 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.)
justify
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 cross-start edge of the first line in the
flexbox is placed flush with the cross-start content edge of the flexbox,
the cross-end edge of the last line in
the flexbox is placed flush with the cross-end 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.
distribute
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.
stretch
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.
Note: Only multi-line
flexboxes ever have free space in the cross
axis for lines to be aligned in, because in a single-line flexbox the sole line
automatically stretches to fill the space.
An illustration of the ‘flex-line-pack’ keywords and their
effects on a multi-line flexbox.
9. Flexbox Layout
Algorithm
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.
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.
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.
To lay out a flexbox and its contents, follow these steps:
Generate anonymous flexbox items around runs of contiguous
inline content in the flexbox, as described in the Flexbox Items section.
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.
Determine the hypothetical main size of items:
If item has a definite preferred size, it is the hypothetical main
size.
Otherwise layout the flexbox items using the shrink-to-fit
algorithm:
In row-direction flexbox, shrink-to-fit size of a flex item along
the main axis is its ‘max-content’, as defined in [CSS3-WRITING-MODES]
In column-direction flexbox, shrink-to-fit size of a flex item
along the main axis is the extent in block direction that it gets
when laid out using its 'fit-content' as its size in inline
direction and using cross-size of flexbox content box as available
measure, also as defined in [CSS3-WRITING-MODES].
In multi-line column-direction flexbox, cross-size of the whole
flexbox content box is used as available measure, not the share of
individual flexbox line, to avoid a circular dependency of line
breaks on shrink-to-fit calculations.
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.
If the flexbox is single-line, collect all the flexbox items into a
single flexbox line.
If the flexbox is multi-line, group the flexbox items into multiple
lines:
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:
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.
for ‘max-content’, the maximum
line length is infinity, constrained by the min and max main size
constraints of the flexbox.
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.
Collect as many consecutive flexbox items as possible, starting from
the first item, while keeping the sum of their margin-box 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 its
size between its minimum and maximum main sizes. The items so collected
form a single flexbox line.
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.
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. If any margins are set to 'auto', consider them
to be set to zero until resolved in a separate step.
For each flexbox line,
Resolve the flexible
lengths 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.
Calculate the leftover free-space by subtracting the sum of the
margin-box main sizes of the items on the line from the main size of
the flexbox's content box.
Resolve 'auto' margins on main axis:
If leftover free-space is positive and any items on this line have
at least one main-axis margin set to 'auto', distribute the
leftover free-space equally to these margins.
If leftover free-space is negative, any main-axis 'auto'
margins on items in this line are set to zero.
Align the items along the main axis per ‘flex-pack’.
Calculate the cross size of each flexbox line. For each flexbox line:
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.
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.
For remaining flexbox items, find the maximum of the cross sizes of
their margin boxes.
The cross size of the flexbox line is the larger of the numbers
found in the previous two steps.
If the flexbox is multi-line, has a definite cross size,
'flex-line-pack' is set to 'stretch' and sum of cross
size of all lines is less than cross size of content box, increase
cross size of each line by equal amount to exactly match the cross size
of content box.
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.
Determine the final cross size of each flexbox item.
If a flexbox item has ‘flex-item-align:stretch'' and its preferred cross
size is 'auto' and its margin-box cross size is smaller than
cross-size of its flexbox line, its final cross size is 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.
If the resulting cross size of any item conflicts with
'min-width', 'max-width', 'min-height' or
'max-height', correct the result to comply with the
restrictions.
Resolve 'auto' margins on cross axis. For each flexbox item,
if its margin box cross size is smaller than cross size of its line and
it has any margins in cross direction set to 'auto', distribute
the difference equally to the auto margins.
For each flexbox line, align the flexbox items per 'flex-item-align'.
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.
Layout all items again in their final size and position.
Implementations can determine when this step is needed and how it can be
optimized, but for precise results it has to be assumed that this step is
performed.
To resolve the flexible
lengths of the items within a flexbox line:
Determine sign of flexibility
Add margin-box hypothetical main sizes of all items, adjusted for
min/max.
If the sum is less than available space, use positive flexibility,
otherwise use negative flexibility.
for the rest of the algorithm use flexibility with the sign determined
in this step
Reset all flexible sizes to their preferred size
Find free space by subtracting sum of margin-box main sizes of flexbox
items from available space.
Distribute free space proportional to flex:
If the free space is positive, but step 1 chose negative
flexibility, do nothing
If the free space is negative, but step 1 chose positive
flexibility, do nothing
Add a portion of free space to each flexible item, proportional to
item's flexibility
Fix min/max violations:
Adjust each flexible item for min/max.
If the size has changed, it is a violation.
The violation may be positive (min violation) or negative (max
violation). Accumulate the difference.
If the sum of all violations is:
Zero
Exit the algorithm.
Positive
Freeze items with max violations, and return to step 2.
Negative
Freeze items with min violations, and return to step 2.
For the purposes of this algorithm, measurements are considered definite if their precise value is known before the
start of the algorithm. For example, sizes in pixels or inches are always
definite; 'auto' and percent may or may not be definite, which depends on
how these values were handled before this algorithm is applied.
10. Page breaks in flexbox
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.
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.
Breaks in and around flexbox are determined as follows:
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.
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:
If flexbox starts on that page: the distance between start of
content box of the flexbox and the end of available space
If flexbox continues from previous page: the size of available
space.
If as a result of this adjustment block-direction size of flexbox
becomes negative, it is set to zero.
Forced breaks on flexbox
items
In a row-direction single-line flexbox, breaks before and after
items apply to the flexbox
In column-direction single-line flexbox and all multi-line
flexboxes:
Forced break before the first item is applied to the flexbox
Forced break after the last item is applied to the flexbox
Forced break before or after any other item terminates the set of
items to be laid out on this page
When necessary, a break inside a flexbox item
is considered as follows:
If the item has “break-inside:avoid”, it is pushed to the next
page
Otherwise, it may be broken, according to breaking rules and
algorithms applicable to its display type.
Forced breaks inside flexbox item content are handled normally, but
in row-direction flexbox they don't affect layout of sibling
flexbox items (e.g. a forced break inside an item doesn't prevent
its next sibling from appearing on the same page)
Column-direction flexbox: single-line
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 flexbox items use the preferred
size, adjusted for min/max.
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.
Set of items that will fit on current page is determined by adding
main-axis margin-box sizes of flexbox items until total size exceeds
available space or a forced break is encountered.
If border box of an item doesn’t fit in available space, a break
inside the item is considered
Items that fit on a page completely or partially are aligned
according to ‘flex-pack’ property, independently from the rest of
flexbox content.
Note that flexible lengths are not recalculated on each page, even
if there is additional free space.
It is the intent of this spec that column-direction
single-line flexbox paginates very 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.
Column-direction flexbox: multi-line
Items are collected in lines and laid out as usual, but in available
space on current page.
If border box of an item doesn’t fit on main-axis and it is the
only item in its line:
If the flexbox is not at the top of the page, it is moved to the
next page.
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.
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.
Breaks inside items (forced or unforced) are not allowed
Row-direction flexbox: single-line
Main-axis space distribution in each line is done based on complete
content of the flexbox and without space constraint in block
direction.
If page size varies and flexbox size depends on page size, this step
needs to be repeated on each page.
Flexbox 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).
Any items with baseline alignment must be aligned before considering
breaks inside items.
If border box of an item doesn’t fit in current page, a break
inside the item is considered
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.
Items that fit completely or partially on current page are aligned
on cross-axis:
For the purposes of cross-axis alignment, minimum of remaining
available space in flexbox and available space at current page is
used.
If an item is broken in the previous step and its alignment is not
baseline, its cross-axis margin-box 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.
Row-direction flexbox: multi-line
Collect items into lines and determine line heights:
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.
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.
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.
Lines are added one at a time, until out of available space or a
forced break is encountered
Breaks inside items (forced or unforced) are not allowed.
If the first flexbox line on a page doesn't fit in cross-axis,
If the flexbox is not at the top of the page, it is moved to the
next page.
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.
If size of flexbox in inline direction is not definite, multi-line
layout algorithm is run using the set of items that have fit on the
current page.
Line packing is done on each page, with content on the page
11. CSSOM
'Flex' property is currently defined as shorthand only,
combining three values. When queried from OM, it is seen as a
string with up to three values, which can be very complicated to deal
with properly.
There should be separate properties to access flexibility components in
OM, such as:
Conformance requirements are expressed with a combination of descriptive
assertions and RFC 2119 terminology. The key words “MUST”, “MUST
NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the
normative parts of this document are to be interpreted as described in RFC
2119. However, for readability, these words do not appear in all uppercase
letters in this specification.
All of the text of this specification is normative except sections
explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples in this specification are introduced with the words “for
example” or are set apart from the normative text with
class="example", like this:
This is an example of an informative example.
Informative notes begin with the word “Note” and are set apart from
the normative text with class="note", like this:
Note, this is an informative note.
12.2. Conformance
classes
Conformance to CSS Flexbox Layout Module is defined for three
conformance classes:
A style sheet is conformant to CSS Flexbox Layout Module if all of its
statements that use syntax defined in this module are valid according to
the generic CSS grammar and the individual grammars of each feature
defined in this module.
A renderer is conformant to CSS Flexbox Layout Module if, in addition to
interpreting the style sheet as defined by the appropriate specifications,
it supports all the features defined by CSS Flexbox Layout Module by
parsing them correctly and rendering the document accordingly. However,
the inability of a UA to correctly render a document due to limitations of
the device does not make the UA non-conformant. (For example, a UA is not
required to render color on a monochrome monitor.)
An authoring tool is conformant to CSS Flexbox Layout Module if it
writes style sheets that are syntactically correct according to the
generic CSS grammar and the individual grammars of each feature in this
module, and meet all other conformance requirements of style sheets as
described in this module.
12.3. Partial implementations
So that authors can exploit the forward-compatible parsing rules to
assign fallback values, CSS renderers must treat as
invalid (and ignore as
appropriate) any at-rules, properties, property values, keywords, and
other syntactic constructs for which they have no usable level of support.
In particular, user agents must not selectively ignore
unsupported component values and honor supported values in a single
multi-value property declaration: if any value is considered invalid (as
unsupported values must be), CSS requires that the entire declaration be
ignored.
12.4. Experimental
implementations
To avoid clashes with future CSS features, the CSS2.1 specification
reserves a prefixed
syntax for proprietary and experimental extensions to CSS.
Prior to a specification reaching the Candidate Recommendation stage in
the W3C process, all implementations of a CSS feature are considered
experimental. The CSS Working Group recommends that implementations use a
vendor-prefixed syntax for such features, including those in W3C Working
Drafts. This avoids incompatibilities with future changes in the draft.
12.5. Non-experimental
implementations
Once a specification reaches the Candidate Recommendation stage,
non-experimental implementations are possible, and implementers should
release an unprefixed implementation of any CR-level feature they can
demonstrate to be correctly implemented according to spec.
To establish and maintain the interoperability of CSS across
implementations, the CSS Working Group requests that non-experimental CSS
renderers submit an implementation report (and, if necessary, the
testcases used for that implementation report) to the W3C before releasing
an unprefixed implementation of any CSS features. Testcases submitted to
W3C are subject to review and correction by the CSS Working Group.
For this specification to be advanced to Proposed Recommendation, there
must be at least two independent, interoperable implementations of each
feature. Each feature may be implemented by a different set of products,
there is no requirement that all features be implemented by a single
product. For the purposes of this criterion, we define the following
terms:
independent
each implementation must be developed by a different party and cannot
share, reuse, or derive from code used by another qualifying
implementation. Sections of code that have no bearing on the
implementation of this specification are exempt from this requirement.
interoperable
passing the respective test case(s) in the official CSS test suite,
or, if the implementation is not a Web browser, an equivalent test. Every
relevant test in the test suite should have an equivalent test created if
such a user agent (UA) is to be used to claim interoperability. In
addition if such a UA is to be used to claim interoperability, then there
must one or more additional UAs which can also pass those equivalent
tests in the same way for the purpose of interoperability. The equivalent
tests must be made publicly available for the purposes of peer review.
implementation
a user agent which:
implements the specification.
is available to the general public. The implementation may be a
shipping product or other publicly available version (i.e., beta
version, preview release, or “nightly build”). Non-shipping product
releases must have implemented the feature(s) for a period of at least
one month in order to demonstrate stability.
is not experimental (i.e., a version specifically designed to pass
the test suite and is not intended for normal usage going forward).
The specification will remain Candidate Recommendation for at least six
months.
Acknowledgments
Thanks for feedback and contributions to Andrew Fedoniouk, Arron
Eicholz, James Elmore, Ben Horst, Boris Zbarsky, Brad Kemper, Brian
Heuston, Christian Stockwell, Christoph Päper, Daniel Holbert, Erik
Anderson, Eugene Veselov, Fantasai, John Jansen, Markus Mielke, Ning
Rogers, Ojan Vafai, Peter Salas, Phil Cupp, Robert O'Callahan, Rossen
Atanassov, Shinichiro Hamaji, Tony Chang.
