1. Introduction
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 CSS 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.
Note: The alignment of text and inline-level content is defined in [CSS-TEXT-3] and [CSS-INLINE-3].
Note: This specification is not intended to change any of the behavior defined in CSS2.1 when the properties defined here are set to their initial values. If implementors or anyone else notices a discrepancy, please report this to the CSSWG as an error.
This section (above) is not normative.
1.1. Module Interactions
This module adds some new alignment capabilities to the block layout model described in [CSS2] chapters 9 and 10, redefines how overconstrained block-level box margins are resolved, and defines the interaction of these new alignment properties with the alignment of table cell content using vertical-align, as defined in [CSS2] chapter 17.
The interaction of these properties with Grid Layout [CSS-GRID-1] and Flexible Box Layout [CSS-FLEXBOX-1] is defined in their respective modules. The property definitions here supersede those in [CSS-FLEXBOX-1] (which have a smaller, earlier subset of permissible values).
No properties in this module apply to the ::first-line
or ::first-letter pseudo-elements.
1.2. Value Definitions
This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.
In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.
1.3. Partial Implementations
Since it is expected that support for the features in this module will be deployed in stages corresponding to the various layout models affected, it is hereby clarified that the rules for partial implementations that require treating as invalid any unsupported feature apply to any alignment keyword which is not supported across all layout modules to which it applies for layout models in which the implementation supports the property in general.
For example, if an implementation supports align-self in [CSS-GRID-1] and [CSS-FLEXBOX-1], then it must treat start as invalid unless it is supported in both grid and flex containers. However if that same implementation does not support align-self for block-level elements at all, then a lack of implementation of align-self: start does not trigger this requirement to treat it as invalid.
2. Overview of Alignment Properties
The box alignment properties in CSS are a set of 6 properties that control alignment of boxes within other boxes. They can be described along two axises:
- which dimension they apply to (main/inline vs. cross/block), and
- whether they control the position of the box within its parent, or the box’s content within itself.
Note: This specification uses the terms “justify” and “align” to distinguish between alignment in the main/inline and cross/block 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 (including CSS Flexbox 1 § 2 Flex Layout Box Model and Terminology)
The following table summarizes the box alignment properties and the display types they can apply to.
| Common | Axis | Aligns | Applies to |
|---|---|---|---|
| justify-content | main/inline |
content within element
(effectively adjusts padding)
| block containers, flex containers, and grid containers |
| align-content | cross/block | ||
| justify-self | inline |
element within parent
(effectively adjusts margins)
| block-level boxes, absolutely-positioned boxes, and grid items |
| align-self | cross/block | absolutely-positioned boxes, flex items, and grid items | |
| justify-items | inline |
items inside box
(controls child items’ justify-self: auto)
| block containers and grid containers |
| align-items | cross/block | flex containers and grid containers |
Note: The *-items properties don’t affect the element itself. When set on a container, they specify the interpretation of any *-self: auto used on children of the container element.
3. Alignment Terminology
Since this module defines alignment properties for all layout modes in CSS, some abstract terminology is introduced:
- 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, and assumes the writing mode of that box. For justify-content and align-content, the alignment subject is defined by the layout mode and refers to some aspect of its contents; it also assumes the writing mode of the box the property is set on.
- 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, and assumes the writing mode of the box establishing the containing block.
- fallback alignment
- Some alignments can only be fulfilled in certain situations or are limited in how much space they can consume; for example, space-between can only operate when there is more than one alignment subject, and baseline alignment, once fulfilled, might not be enough to absorb all the excess space. In these cases a fallback alignment takes effect (as defined below) to fully consume the excess space.
4. Alignment Keywords
All of the alignment properties use a common set of keyword values, which are defined in this section. Keywords fall into three categories:
- positional alignment
- These keywords define alignment as an absolute position within the alignment container.
- baseline alignment
- These keywords define alignment as a relationship among the baselines of multiple alignment subjects within an alignment context.
- distributed alignment
- These keywords define alignment as a distribution of space among alignment subjects.