CSS Box Alignment Module Level 3

Abstract

This module contains the features of CSS relating to the alignment of boxes within their containers in the various CSS box layout models: block layout, table layout, flex layout, and grid layout. (The alignment of text and inline-level content is defined in [[CSS3TEXT]] and [[CSS3LINE]].) CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc.

Status of this document

The following features are at risk: …

Table of contents

Introduction

This section is not normative.

CSS Levels 1 and 2 allowed for the alignment of text via 'text-align' and the alignment of blocks by balancing ''auto'' margins. However, except in table cells, vertical alignment was not possible. As CSS3 adds further capabilities, the ability to align boxes in various dimensions becomes more critical. This module attempts to create a cohesive and common box alignment model to share among all of CSS.

The alignment of text and inline-level content is defined in [[CSS3TEXT]] and [[CSS3LINE]].

Inspiration for this document:

• summary of a discussion for implementing <CENTER>
• Minutes from March 2008 F2F
• fantasai's attempt to merge all alignment properties

Module interactions

This module adds some new alignment capabilities to the block layout model described in [[!CSS21]] chapters 9 and 10 and defines the interaction of these properties with the alignment of table cell content using 'vertical-align', as defined in [[!CSS21]] chapter 17. The interaction of these properties with Grid Layout [[!CSS3-GRID-LAYOUT]] and Flexible Box Layout [[!CSS3-FLEXBOX]] is defined in their respective modules.

No properties in this module apply to the ::first-line or ::first-letter pseudo-elements.

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 [[CSS3VAL]], when combined with this module, adds the ''initial'' keyword as a possible property value.

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.

Overview of Alignment Properties

The alignment properties in CSS can be described along two axes:

• which dimension they apply to (inline vs. stacking), and
• whether they control the position of the box within its parent, or the box's content within itself.

This proposal uses the terms 'justify' and 'align' to distinguish between alignment in the inline and stacking dimensions, respectively. The choice is somewhat arbitrary, but having the two terms allows for a consistent naming scheme that works across all of CSS's layout models.

The following table summarizes the proposed alignment properties and the display types they can apply to.

Common	Axis	Aligns	Applies to
'justify-self'	inline	element within parent (effectively adjusts margins)	block-level elements and grid items
'align-self'	stacking		flex items and grid items
'justify-content'	inline	content within element (effectively adjusts padding)	block containers and flex containers
'align-content'	stacking		block containers and flex containers
'justify-items'	inline	items inside element (controls child items’ ''align/justify-self: auto'')	grid containers
'align-items'	stacking		flex containers and grid containers

The exact behavior of these properties on layout models other than Flexbox is still to be determined. This is a First Public Working Draft and is NOT STABLE.

The '-items' values don't affect the element itself. When set on a flex container or grid container, they specify the interpretation of any ''align/justify-self: auto'' used on the items in the container element.

True alignment vs. safe alignment. Maybe make safe by default, true if ''true'' is specified? Or safe/true depending on layout model (e.g. safe for blocks, true for flexbox)? Current draft introduces a ''true'' keyword, but other options should be considered.

Alignment Values

All of the alignment properties use a common set of values, defined below.

alignment subject

The alignment subject is the thing or things being aligned by the property. For 'justify-self' and 'align-self', the alignment subject is the margin box of the box the property is set on. For 'justify-content' and 'align-content', the alignment subject is defined by the layout mode.

alignment container

The alignment container is the rectangle that the alignment subject is aligned within. This is defined by the layout mode, but is usually the alignment subject’s containing block.

Positional Alignment: the ''center'', ''start'', ''end'', ''self-start'', ''self-end'', ''flex-start'', ''flex-end'', ''left'', and ''right'' keywords

...

<item-position> = center | stretch | start | end | self-start | self-end | 
                  flex-start | flex-end | left | right;
<content-position> = center | start | end | flex-start | flex-end | left | right;

''center''

Centers the alignment subject within its alignment container.

''stretch''

If the 'width' or 'height' (as appropriate) of the alignment subject is ''auto'', its used value is the length necessary to make the alignment subject’s outer size as close to the size of the alignment container as possible, while still respecting the constraints imposed by 'min/max-width/height'. Otherwise, this is equivalent to ''start''.

''start''

Aligns the alignment subject to be flush with the alignment container’s start edge.

''end''

Aligns the alignment subject to be flush with the alignment container’s end edge.

''self-start''

Aligns the alignment subject to be flush with the edge of the alignment container corresponding to the alignment subject’s start side.

''self-end''

Aligns the alignment subject to be flush with the edge of the alignment container corresponding to the alignment subject’s end side.

''flex-start''

Only used in flex layout. [[!CSS3-FLEXBOX]] Aligns the alignment subject to be flush with the edge of the alignment container corresponding to the flex container’s main-start or cross-start side, as appropriate. When used in layout modes other than Flexbox, this is equivalent to ''start''.

''flex-end''

Only used in flex layout. Aligns the alignment subject to be flush with the edge of the alignment container corresponding to the flex container’s main-end or cross-end side, as appropriate. When used in layout modes other than Flexbox, this is equivalent to ''start''.

''left''

Aligns the alignment subject to be flush with the alignment container’s line-left edge. If the property's axis is not parallel with the inline axis, this is equivalent to ''start''.

''right''

Aligns the alignment subject to be flush with the alignment container’s line-right edge. If the property's axis is not parallel with the inline axis, this is equivalent to ''start''.

Add example images.

Baseline Alignment: the ''baseline'' keyword

...

''baseline''

For table cells, grid items, and flex items, aligns the cell/item's first formatted line's baseline, if any, with the same baseline in other ''baseline''-aligned cells/items in the row/column (as appropriate for the axis). This is similar to the behavior of ''vertical-align: baseline'' on table cells; see [[!CSS21]] chapter 17 for details. If the content's position is not fully determined by baseline alignment, the content is start-aligned insofar as possible while preserving the baseline alignment. (Content that has no first-line baseline is thus also start-aligned.)

Add example images.

Distributed Alignment: the ''space-between'', ''space-around'', and ''space-evenly'' keywords

The distribution values are used by 'justify-content' and 'align-content' to distribute the items in the alignment subject evenly between the start and end edges of the alignment container.

<content-distribution> = space-between | space-around | space-evenly | stretch

''space-between''

The items are evenly distributed in the alignment container. The first item is placed flush with the start edge of the alignment container, the last item is placed flush with the end edge of the alignment container, and the remaining items are distributed so that the spacing between any two adjacent items is the same. Unless otherwise specified, this value falls back to ''start''.

''space-around''

The items are evenly distributed in the alignment container, with a half-size space on either end. The items are distributed so that the spacing between any two adjacent items is the same, and the spacing before the first and after the last item is half the size of the other spacing. Unless otherwise specified, this value falls back to ''center''.

''space-evenly''

The items are evenly distributed in the alignment container, with a full-size space on either end. The items are distributed so that the spacing between any two adjacent items, before the first item, and after the last item is the same. Unless otherwise specified, this value falls back to ''center''.

''stretch''

If the combined size of the items is less than the size of the alignment container, any ''auto''-sized items have their size increased equally so that the combined size exactly fills the alignment container. Otherwise, or if there are no ''auto''-sized items, this value is identical to ''flex-start''. (For layout modes other than flex layout, ''flex-start'' is identical to ''start''.)

Add example images.

Overflow Alignment: the ''safe'' and ''true'' keywords

When the alignment subject is larger than the alignment container, it will overflow. Some alignment modes, if honored in this situation, may cause data loss: for example, if the contents of a sidebar are centered, when they overflow they may send part of their boxes past the viewport's start edge, which can't be scrolled to.

To help combat this problem, the overflow behavior of an element's alignment mode can be explicitly specified. "True" alignment honors the alignment mode, even if it causes data loss, while "safe" alignment adjusts the alignment mode in an attempt to avoid data loss.

If the overflow alignment isn't explicitly specified, the default overflow alignment is determined by the layout mode. Document-centric layout modes, such as block layout, default to "safe" overflow alignment, while design-centric layout modes, such as flex layout, default to "true" overflow alignment.

<overflow-position> = true | safe

''safe''

If the size of the alignment subject overflows the alignment container, the alignment subject is instead aligned as if the alignment mode were ''start''.

''true''

Regardless of the relative sizes of the alignment subject and alignment container, the given alignment value is honored.

Transplant example 10 from flexbox.

Content Distribution: the 'justify-content' and 'align-content' properties

Aligns the contents of the box as a whole along the box's inline/row/main axis. Values other than ''auto'' are defined above.

Block Layout:

All values other than ''auto'' force the block container to establish a new formatting context. ''auto'' otherwise behaves as ''start''.

The alignment container is the block container’s content box. The alignment subject is the entire contents of the block.

The 'align-content' property applies along the block axis, but the <content-distribution> values behave as their fallback values. The 'justify-content' property does not apply to and has no effect on block containers.

Multicol Layout:

''auto'' behaves as ''start''.

The alignment container is the multi-column element’s content box. The alignment subject is the column boxes, as a unit.

The 'align-content' property applies along the block axis, but the <content-distribution> values behave as their fallback values. The 'justify-content' property does not apply to and has no effect on multi-column elements.

Flex Layout:

''auto'' computes to ''stretch''.

The alignment container is the flex container’s content box. For 'justify-content', the alignment subject is the flex items in each flex line; for 'align-content', the alignment subject is the flex lines.

The 'align-content' property applies along the cross axis. The 'justify-content' property applies along the main axis, but ''stretch'' behaves as ''start''.

See [[!CSS3-FLEXBOX]] for details.

Grid Layout:

''auto'' computes to ''stretch''.

The alignment container is the grid container’s content box. The alignment subject is the bounds of the grid. Need to dfn a better term for this in Grid.

The 'align-content' property applies along the block (column) axis. The 'justify-content' property applies along the inline (row) axis. In both properties, the <content-distribution> values behave as their fallback values.

Self-Alignment: Aligning the Box within its Parent

The 'justify-self' and 'align-self' properties control alignment of the box within its containing block.

Inline/Main-Axis Alignment: the 'justify-self' property

Justifies the box within its parent along the inline/row axis: the box's outer edges are aligned within its containing block as described below.

''auto''

For block-level elements, use alignment specified by the 'justify-content' property of the containing block. For grid items, indicates that the element should stretch to fill its slot.

''baseline''

Shifts the box such that the baseline of its first formatted line aligns with the corresponding baselines of other ''baseline''-aligned siblings in the same column.

Define alignment of first lines with opposite writing modes.

''start''

Start-aligns the box within its containing block.

''center''

Centers the box within its containing block.

''end''

End-aligns the box within its containing block.

''stretch''

Sizes the box to exactly fit its containing block.

''true''

If specified, alignment is "true", and may cause the box to overflow the start edge of the containing block. Otherwise, the box is forced to start-align when its outer measure is wider than the containing block.

In terms of CSS2.1 block-level formatting, the rules for "over-constrained" computations in section 10.3.3 are used only when the element's margin box overflows the containing block and the ''true'' keyword is not specified. Otherwise those rules are ignored in favor of alignment as specified above, and the used value of the end margin is not adjusted to correct for the over-constraint.

For block-level elements that establish a block formatting context and are placed next to a float, alignment is with respect to the available space (subtracting out from the containing block measure the space taken up by the float), not with respect to the containing block. (Note: This is the legacy behavior of HTML align.)

This property will replace 'grid-column-align'.

Stacking/Cross-Axis Alignment: the 'align-self' property

Aligns the box within its parent along the block/column/cross axis: the box's outer edges are aligned within its containing block as described below.

''auto''

For flex items, computes to alignment specified by the 'align-items' property of the flex container. For grid items, computes to ''stretch''.

''baseline''

Shifts the box such that the baseline of its first formatted line aligns with the corresponding baselines of other ''baseline''-aligned siblings in the same row/line.

''head''

Head-aligns the box within its containing block.

''foot''

Foot-aligns the box within its containing block.

''center''

Centers the box within its containing block.

''stretch''

Sizes the box to exactly fit its containing block.

''true''

If specified, alignment is "true", and may cause the box to overflow the head edge of the containing block. Otherwise, the box is forced to head-align if its outer extent is longer than the containing block.

For flex items, if the "head" and "foot" are not in the alignment dimension, the "start" and "end" sides are used instead.

Default Alignment of Child Items

The 'align-items' and 'justify-items' properties, when set on a flex or grid container, set the default 'align-self' and 'justify-self' behavior of the items contained by the element.

Inline/Main-Axis Alignment: the 'justify-items' property

This could be applied to grid elements and set the default alignment of the grid items. It mainly exists because Flexbox wants 'align-items'; see below.

This would, in conjunction with 'text-align', implement the HTML align attribute and <center>. The weird behavior of ''auto'' is for that and because ''display: block'' elements are essentially transparent, layout-wise, so passing through the alignment unchanged is useful and probably intuitive to authors (though it's really weird for implementers).

Stacking/Cross-Axis Alignment: the 'align-items' property

Sets the default 'align-self' of the flex container's children or the grid container's items. The ''auto'' value computes to ''stretch'' on flex and grid containers.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [[!RFC2119]]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformance classes

Conformance to CSS Box Alignment Module Level 3 is defined for three conformance classes:

style sheet

A CSS style sheet.

renderer

A UA that interprets the semantics of a style sheet and renders documents that use them.

authoring tool

A UA that writes a style sheet.

A style sheet is conformant to CSS Box Alignment Module Level 3 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 Box Alignment Module Level 3 if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by CSS Box Alignment Module Level 3 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 Box Alignment Module Level 3 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.

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.

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.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group's website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

CR exit criteria

[Change or remove the following CR exit criteria if the spec is not a module, but, e.g., a Note or a profile. This text was decided on 2008-06-04.]

For this specification to be advanced to Proposed Recommendation, there must be at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products, there is no requirement that all features be implemented by a single product. For the purposes of this criterion, we define the following terms:

independent

each implementation must be developed by a different party and cannot share, reuse, or derive from code used by another qualifying implementation. Sections of code that have no bearing on the implementation of this specification are exempt from this requirement.

interoperable

passing the respective test case(s) in the official CSS test suite, or, if the implementation is not a Web browser, an equivalent test. Every relevant test in the test suite should have an equivalent test created if such a user agent (UA) is to be used to claim interoperability. In addition if such a UA is to be used to claim interoperability, then there must one or more additional UAs which can also pass those equivalent tests in the same way for the purpose of interoperability. The equivalent tests must be made publicly available for the purposes of peer review.

implementation

a user agent which:

1. implements the specification.
2. is available to the general public. The implementation may be a shipping product or other publicly available version (i.e., beta version, preview release, or “nightly build”). Non-shipping product releases must have implemented the feature(s) for a period of at least one month in order to demonstrate stability.
3. is not experimental (i.e., a version specifically designed to pass the test suite and is not intended for normal usage going forward).

The specification will remain Candidate Recommendation for at least six months.

Acknowledgments

Special thanks goes to Markus Mielke, Alex Mogilevsky, and the participants in the CSSWG's March 2008 F2F alignment discussions.

References

Normative references

Other references

Index

Property index