CSS Box Alignment Module Level 3

Abstract

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc. This module contains the features of CSS relating to alignment. It includes and extends the alignment functionality of CSS level 2 [CSS21] to allow alignment in the block axis and to control the alignment of other CSS layout models.

Status of this document

This is a public copy of the editors' draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as 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 “www-style” in the subject, preferably like this: “[www-style] …summary of comment…”

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

The following features are at risk: …

Table of contents

• 1. Introduction
  • 1.1. Module interactions
  • 1.2. Values
• 2. Overview of Alignment Properties
• 3. Self-Alignment: Aligning the Box within its Parent
  • 3.1. Inline/Main-Axis Alignment: the ‘box-justify’ property
  • 3.2. Stacking/Cross-Axis Alignment: the ‘box-align’ property
• 4. Content-Alignment: Aligning the Content within the Box
  • 4.1. Inline/Main-Axis Alignment: the ‘content-justify’ property
  • 4.2. Stacking/Cross-Axis Alignment: the ‘content-align’ property
• 5. Default Alignment of Child Items
  • 5.1. Inline/Main-Axis Alignment: the ‘items-justify’ property
  • 5.2. Stacking/Cross-Axis Alignment: the ‘items-align’ property
• 6. Conformance
  • 6.1. Document conventions
  • 6.2. Conformance classes
  • 6.3. Partial implementations
  • 6.4. Experimental implementations
  • 6.5. Non-experimental implementations
  • 6.6. CR exit criteria
• Acknowledgments
• References
  • Normative references
  • Other references
• Index
• Property index

1. 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 alignment model to share among all of CSS.

Inspiration for this document:

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

1.1. 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 Flexbox Layout [CSS3-FLEXBOX] is defined in their respective modules.

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

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 [[CSS3VALUES]], 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.

2. Overview of Alignment Properties

The alignment properties in CSS can be described along two axes: which dimension they apply to, and whether they control the position of the box within its parent, or the box's content within itself.

True alignment vs. safe alignment. Maybe make safe by default, true if ‘true’ is specified? (Using that in the spec for now.) Or safe/true depending on layout model (e.g. safe for blocks, true for flexbox).

The following table summarizes the proposed alignment properties and their relation to the alignment properties existing in other modules.

3. Self-Alignment: Aligning the Box within its Parent

The ‘box-justify’ and ‘box-align’ properties control alignment of the box within its parent.

3.1. Inline/Main-Axis Alignment: the ‘box-justify’ 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 ‘content-justify’ property of the containing block. For grid items, indicates that the element should stretch to fill its slot.

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

‘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 would replace ‘grid-column-align’.

3.2. Stacking/Cross-Axis Alignment: the ‘box-align’ 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 flexbox items, computes to alignment specified by the ‘child-align’ property of the flexbox 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.

‘before’

Before-aligns the box within its containing block.

‘after’

After-aligns the box within its containing block.

‘middle’

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 before edge of the containing block. Otherwise, the box is forced to before-align if its outer extent is longer than the containing block.

For flex items "before" and "after" are interpreted relative to the flex flow, not the writing mode. (Is this actually what we want? Even in the overflow-correction case?)

This replaces ‘flex-item-align’.

4. Content-Alignment: Aligning the Content within the Box

The ‘content-justify’ and ‘content-align’ properties control alignment of the box's content within the box.

4.1. Inline/Main-Axis Alignment: the ‘content-justify’ property

Gives the default alignment of the box's content along the inline/row axis. For block containers, this simply changes the meaning of ‘box-justify: auto’ on its children. For flexbox containers, this aligns the contents of each flexbox line within its flexbox line box. See [[!CSS3FLEXBOX]] for exact details.

‘auto’

If the element has ‘display: block’ and ‘box-justify: auto’, computes to the value inherited from the parent. Otherwise computes to ‘start’.

‘start’

Start-aligns the content within its box.

‘end’

End-aligns the content within its box.

‘left’

Aligns content to the line-left edge. On a flexbox container, this is treated as ‘auto’ if the line-left direction is in the wrong dimension.

‘right’

Aligns content to the line-right edge. On a flexbox container, this is treated as ‘auto’ if the line-right direction is in the wrong dimension.

‘center’

Centers the content within its box

‘distribute’

Distributes the content evenly throughout the line by adjusting inter-child spacing. If there is only one child (or if the element is a block container), this is equivalent to centering.

‘space’

Distributes the content evenly throughout the line by adjusting inter-child spacing and applying half of that spacing between the first/last child and the box edges. If there is only one child (or if the element is a block container), this is equivalent to centering.

‘true’

If specified, alignment is "true", and may cause the contents to overflow the start edge of the box. Otherwise, the content is forced to start-align if its total outer measure (before ‘distribute’ or ‘space’ is applied) is wider than the containing block.

This property would replace ‘flex-pack’ and 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).

4.2. Stacking/Cross-Axis Alignment: the ‘content-align’ property

Aligns the box's content within the box along the block/column/cross axis. Values have the following meanings:

‘auto’

For block containers, equivalent to ‘before’, except that it does not cause the block to establish a block formatting context. For table cells, defers alignment to ‘vertical-align’ as specified in [CSS21] chapter 17. For flexbox containers, it causes any positive free space to be distributed equally across the lines. [CSS3-FLEXBOX]

‘before’

Before-aligns the box's content within its content box: the content is laid out beginning at the box's before content edge.

‘middle’

Centers the box's content within its content box: the content is centered between the box's before and after content edges.

‘after’

After-aligns the box's content within its content box: the content is laid out so that it finishes at the after content edge.

‘baseline’

For table cells, grid items, and flexbox items, aligns this elements's first formatted line's baseline, if any, with the same baseline in other ‘baseline’-aligned cells/items in the same row. This is equivalent to the behavior of ‘vertical-align: baseline’ on table cells; see [CSS21] chapter 17 for details. If size constraints prevent the baselines from fully aligning, alignment is as close as possible. If the content's position is not fully determined by baseline alignment, the content is before-aligned insofar as possible while preserving the baseline alignment. (Content that has no first-line baseline is thus also before-aligned.)

‘distribute’

For flexbox containers, distributes lines evenly by adjusting inter-line spacing. If there is only one line (or if the element is container of line boxes), this is equivalent to centering. UAs may also apply ‘distribute’ to lines in a block container.

‘space’

For flexbox containers, distributes lines evenly by adjusting inter-line spacing and applying half of that spacing between the first/last child and the box edges. If there is only one line (or if the element is not a container of line boxes), this is equivalent to centering. UAs may also apply ‘distribute’ to lines in a block container.

‘true’

If specified, alignment is "true", and may cause the content to overflow the before edge of the containing block. Otherwise, the content is forced to before-align if is longer than the box's content area, and will thus overflow only the after edge.

All values other than ‘auto’ cause a block box to establish a block formatting context such that its margins do not collapse with its children and floats do not intrude into its content box.

For flexbox containers "before" and "after" are interpreted relative to the flex flow, not the writing mode. Is this actually what we want? Even in the overflow-correction case?

This would replace ‘flex-line-pack’.

5. Default Alignment of Child Items

The ‘items-align’ and ‘items-justify’ properties, when set on a flexbox or grid container, set the default ‘box-align’ and ‘box-justify’ behavior of the items contained by the element.

5.1. Inline/Main-Axis Alignment: the ‘items-justify’ property

This could be applied to grid elements and set the default alignment of the grid items. It mainly exists because Flexbox requires ‘items-align’ (i.e. ‘flex-align’); see below.

Sets the default ‘box-justify’ of the grid container's items.

5.2. Stacking/Cross-Axis Alignment: the ‘items-align’ property

Sets the default ‘box-align’ of the flexbox container's children or the grid container's items. The ‘auto’ value computes to ‘stretch’ on flexbox and grid containers.

This property replaces ‘flex-align’, which sets the default ‘flex-item-align’ of its children.

6. Conformance

6.1. Document conventions

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

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

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

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

Note, this is an informative note.

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

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

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

6.5. Non-experimental implementations

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

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

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

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

[CSS21]

Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-CSS2-20110607

[CSS3-FLEXBOX]

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

[CSS3-GRID-LAYOUT]

Alex Mogilevsky; et al. CSS Grid Layout. 22 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-css3-grid-layout-20120322/

[RFC2119]

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

Other references

Index

• ‘after’, 3.2., 4.2.
• authoring tool, 6.2.
• ‘auto’, 3.1., 3.2., 4.1., 4.2.
• ‘baseline’, 3.2., 4.2.
• ‘before’, 3.2., 4.2.
• box-align, 3.2.
• box-justify, 3.1.
• ‘center’, 3.1., 4.1.
• content-align, 4.2.
• content-justify, 4.1.
• ‘distribute’, 4.1., 4.2.
• ‘end’, 3.1., 4.1.
• items-align, 5.2.
• items-justify, 5.1.
• ‘left’, 4.1.
• ‘middle’, 3.2., 4.2.
• renderer, 6.2.
• ‘right’, 4.1.
• ‘space’, 4.1., 4.2.
• ‘start’, 3.1., 4.1.
• ‘stretch’, 3.2.
• style sheet
  • as conformance class, 6.2.
• ‘true’, 3.1., 3.2., 4.1., 4.2.

Property index