CSS Box Sizing Module Level 4

1. Introduction

This is a diff spec over CSS Sizing Level 3. It is currently an Exploratory Working Draft: if you are implementing anything, please use Level 3 as a reference. We will merge the Level 3 text into this draft once it reaches CR.

1.1. Module interactions

This module extends the width, height, min-width, min-height, max-width, max-height, and column-width features defined in [CSS2] chapter 10 and in [CSS3COL]

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 keywords as their property value. For readability they have not been repeated explicitly.

2. Terminology

CSS Sizing 3 §2 Terminology

3. Specifying Box Sizes

CSS Sizing 3 §3 Specifying Box Sizes

3.1. Sizing Properties

Add shorthands. <https://github.com/w3c/csswg-drafts/issues/820>

3.2. New Sizing Values: the stretch, fit-content, and contain keywords

Name:	width, height, inline-size, block-size, min-width, min-height, min-inline-size, min-block-size, max-width, max-height, max-inline-size, max-block-size
New values:	stretch \| fit-content \| contain

stretch: Applies stretch-fit sizing, attempting to match the size of the box’s margin box to the size of its containing block. See § 7.1 Stretch-fit Sizing: filling the containing block.
fit-content: Essentially fit-content(stretch) i.e. min(max-content, max(min-content, stretch)).
contain: If the box has a preferred aspect ratio, applies contain-fit sizing, attempting to fit into the box’s constraints while maintaining its preferred aspect ratio insofar as possible. See § 7.2 Contain-fit Sizing: stretching while maintaining an aspect ratio.
If the box has no preferred aspect ratio, applies stretch-fit sizing.

4. Aspect Ratios

This section is a rough draft proposal. See discussion in Issue 333 and Issue 1173.

4.1. Intrinsic Aspect Ratios: the aspect-ratio property

Name:	aspect-ratio
Value:	auto \|\| <ratio>
Initial:	auto
Applies to:	all elements except inline boxes and internal ruby or table boxes
Inherited:	no
Percentages:	n/a
Computed value:	specified keyword or a pair of numbers
Canonical order:	per grammar
Animation type:	discrete

This property sets a preferred aspect ratio for the box, which will be used in the calculation of auto sizes and some other layout functions. The box’s automatic sizes are calculated the same as for a replaced element with an intrinsic aspect ratio and no intrinsic dimension in that axis, see e.g. CSS2 § 10 and CSS Flexible Box Model Level 1 § 9.2. The axis in which the preferred size calculation depends on this aspect ratio is called the ratio-dependent axis, and the resulting size is definite if its input sizes are also definite.

auto: Replaced elements with an intrinsic aspect ratio use that aspect ratio; otherwise the box has no preferred aspect ratio. Size calculations involving intrinsic aspect ratio work with the content box dimensions always.
<ratio>: The box’s preferred aspect ratio is the specified ratio of width / height. Size calculations involving preferred aspect ratio work with the dimensions of the box specified by box-sizing.
auto && <ratio>: If both auto and a <ratio> are specified together, the preferred aspect ratio is the specified ratio of width / height unless it is a replaced element with an intrinsic aspect ratio, in which case that aspect ratio is used instead. In all cases, size calculations involving this aspect ratio work with the content box dimensions always.

Note: If a box has both a width and a height that are not automatic (or, in the case of a flex item, both a content flex basis and a non-automatic preferred cross size), then the preferred aspect ratio has no effect: at least one of these sizes must be auto (/content) for the preferred aspect ratio to have an impact on sizing.

This example sets each item in the grid to render as a square, determining the number of items and their widths by the available space.

<ul>
  <li>…
  <li>…
  <li>…
  <li>…
</ul>

ul {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(12em, 1fr));
}
li {
  aspect-ratio: 1/1;
  overflow: auto;
}

This example uses the iframe element’s width and height attributes to set the aspect-ratio property, giving the iframe an aspect ratio to use for sizing so that it behaves exactly like an image with that aspect ratio.

<iframe
  src="https://www.youtube.com/embed/0Gr1XSyxZy0"
  width=560
  height=315>

@supports (aspect-ratio: attr(width) / 1) {
  iframe {
    aspect-ratio: attr(width) / attr(height);
    width: 100%;
    height: auto;
  }
}

In the following example:

<div id=container style="height: 100px; float: left;">
  <div id=item style="height: 100%; aspect-ratio: 1/1;">content</div>
</div>

Since the height of the #item is a percentage that resolves against a definite container, the width of the item resolves to 100px for both its intrinsic size contributions as well as for final layout, so the container also sizes to a width of 100px.

<div id=container style="height: auto; float: left;">
  <div id=item style="height: 100%; aspect-ratio: 1/1;">content</div>
</div>

In this next example, the percentage height of the item cannot be resolved and behaves as auto (see CSS 2.1 §10.5 Content height: the 'height' property). Since both axes now have an automatic size, the height becomes the ratio-dependent axis. Calculating the intrinsic size contributions of the box produces a width derived from its content, and a height calculated from that width and the aspect ratio, yielding a square box (and a container) sized to the width of the word “content”.

On non-replaced elements with an auto inline size (or any replaced element whose intrinsic block size depends on its inline size), the intrinsic block sizes of the box are assumed to be zero when applying min-block-size to the aspect ratio calculations, and assumed to be infinity when applying max-block-size to the aspect ratio calculations. These limits take effect as usual for non-replaced elements once the inline size is resolved.

For example, given a (horizontal writing mode) element with

width: auto;
min-height: min-content;
aspect-ratio: 1/1;

using the aspect ratio to resolve the width would require knowing the min-content height of the element.

Since for a non-replaced element, this value is not known until the width is resolved, we assume the min-height value is zero while resolving the width.

Then, once the width is known, we resolve the height, taking into account the min-content minimum.

Note: Having a preferred aspect ratio does not make a box into a replaced element; layout rules specific to replaced elements generally do not apply to non-replaced boxes with a preferred aspect ratio. For example, a non-replaced absolutely-positioned box treats justify-self: normal as stretch, not as start (CSS Box Alignment 3 §6.1.2 Absolutely-Positioned Boxes).

CSS2.1 does not cleanly differentiate between replaced elements vs. elements with an aspect ratio; need to figure out specific cases that are unclear and define them, either in the appropriate Level 3 spec or here.

4.1.1. Automatic Content-based Minimum Sizes

In order to avoid unintentional overflow, the automatic minimum size in the ratio-dependent axis of a box with a preferred aspect ratio that is neither a replaced element nor a scroll container is its min-content size clamped from above by its maximum size.

In the following example, the box is as wide as the container (as usual), and its height is as tall as needed to contain its content but at least as tall as it is wide.

div {
  aspect-ratio: 1/1;
  /* 'width' and 'height' both default to 'auto' */
}

+----------+  +----------+  +----------+
| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
| ~~~~~~~  |  | ~~~~~~~~ |  | ~~~~~~~~ |
|          |  | ~~~      |  | ~~~~~~~~ |
+----------+  +----------+  | ~~~~~~~~ |
                            | ~~~~~~   |
                            +----------+

When overflow: auto is specified, however, even the box with excess content maintains the 1:1 aspect ratio.

div {
  overflow: auto;
  aspect-ratio: 1/1;
}

+----------+  +----------+  +----------+
| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~^|
| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
| ~~~~~~~  |  | ~~~~~~~~ |  | ~~~~~~~~ |
|          |  | ~~~      |  | ~~~~~~~~v|
+----------+  +----------+  +----------+

Overriding the min-height property also maintains the 1:1 aspect ratio, but will result in content overflowing the box if it is not otherwise handled.

div {
  aspect-ratio: 1/1;
  min-height: 0;
}

+----------+  +----------+  +----------+
| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
| ~~~~~~~  |  | ~~~~~~~~ |  | ~~~~~~~~ |
|          |  | ~~~      |  | ~~~~~~~~ |
+----------+  +----------+  +-~~~~~~~~-+
                              ~~~~~~

This automatic minimum operates in both axes. Consider this example:

<div style="height: 100px; aspect-ratio: 1/1;">
  <span style="display: inline-block; width: 50px;"></span>
  <span style="display: inline-block; width: 150px;"></span>
</div>

The width of the container, being auto, resolves through the aspect ratio to 100px. However, its min-width, being auto, resolves to 150px. The resulting width of the container is thus 150px. To ignore the contents when sizing the container, min-width: 0 can be specified.

5. Intrinsic Size Determination

5.1. Overriding Contained Intrinsic Sizes: the contain-intrinsic-size property

Name:	contain-intrinsic-size
Value:	none \| <length>{1,2}
Initial:	none
Applies to:	elements with size containment
Inherited:	no
Percentages:	n/a
Computed value:	as specified, with <length> values computed
Canonical order:	per grammar
Animation type:	by computed value type

This property allows elements with size containment to specify an explicit intrinsic inner size, causing the box to size as if its in-flow content totals to a width and height matching the specified explicit intrinsic inner size (rather than sizing as if it were empty).

Note: This is not always equivalent to laying out as if the element had one child of the specified explicit intrinsic inner size.

Note: An element with size containment is laid out as if it had no contents [CSS-CONTAIN-1], which in many cases this will cause the element to collapse to zero inner height. This can be corrected with an explicit height chosen to show the expected contents, but that can have unintended effects in some layout systems, such as Flex and Grid Layout, which treat an explicit height as a stronger command than an implicit content-based height. The element thus might lay out substantially differently than it would have were it simply filled with content up to that height. Providing an explicit intrinsic inner size for the element preserves the performance benefits of ignoring its contents for layout while still allowing it to size as if it had content.

Values are defined as:

none: Does not specify an explicit intrinsic inner size for elements with size containment.
<length>{2}: If the element has size containment, specifies an explicit intrinsic inner size. The first <length> provides the inner width of the element, the second provides the inner height. If the second <length> is omitted, it defaults to the same value as the first.

5.1.1. Interaction With overflow: auto

The contain-intrinsic-size property provides an estimate of how large the author expects the content of an element to be, but this estimate is not actual content and does not represent anything that needs to be shown to the user. Therefore, an element with overflow: auto must not generate scrollbars as a consequence of contain-intrinsic-size.

However, if contain-intrinsic-size indicates a size large enough that the element would generate scrollbars if it contained actual content of that size, then the element must be sized as if it generated those scrollbar(s) in accordance with such hypothetical content.

In the following example code:

div {
  width: max-content;
  contain-intrinsic-size: 100px 100px;
  overflow: auto;
}

The element ends up being 100px wide and 100px tall: contain-intrinsic-size provides the max-content width, and also the height.

If the element then ended up with content that was 150px tall, it would show a vertical scrollbar; if the scrollbar is not overlay, it will take up some of that 100px width, leaving a smaller amount (roughly 84px, typically) for the content to flow into. (See CSS Overflow 3 §3.2 Scrollbars and Layout.)

Even though there’s now less than 100px of horizontal space available for the content, it will not generate a horizontal scrollbar just because contain-intrinsic-size indicates a 100px width; that would only happen if the actual content had something unbreakable and wider than the remaining space.

In contrast, in the following example code:

div {
  width: max-content;
  contain-intrinsic-size: 100px 100px;
  height: 50px;
  overflow: auto;
}

The element has a fixed 50px height, but contain-intrinsic-size indicates a 100px “estimated content height”. The element thus assumes that it will need a vertical scrollbar when it’s filled with actual content, resulting in a max-content width a little more than 100px (roughly 116px, typically), to accommodate the estimated 100px of max-content width from contain-intrinsic-size, and as well as the vertical scrollbar width (roughly 16px, typically).

However, even though the element reserves space on the assumption of needing a scrollbar, it will not actually generate one unless the actual content overflows: if it ends up containing content that’s less than 50px tall, no vertical scrollbar will be generated at all, but the element will still be 116px wide.

6. Intrinsic Size Contributions

A box’s min-content contribution/max-content contribution in each axis is the size of the content box of a hypothetical auto-sized float that contains only that box, if that hypothetical float’s containing block is zero-sized/infinitely-sized.

Note: This specification does not define precisely how to determine these sizes. Please refer to [CSS2], the relevant CSS specification for that display type, the rules for handling percentages (below), and/or existing implementations for further details.

7. Extrinsic Size Determination

CSS Sizing 3 §5 Extrinsic Size Determination

7.1. Stretch-fit Sizing: filling the containing block

Stretch-fit sizing tries to set the box’s used size to the length necessary to make its outer size as close to filling the containing block as possible while still respecting the constraints imposed by min-height/min-width/max-height/max-width.

Formally, its behavior is the same as specifying an automatic size together with a self-alignment property value of stretch (in the relevant axis), except that the resulting box, which can end up not exactly fitting its alignment container, can be subsequently aligned by its actual self-alignment property value.

Additionally, in formatting contexts and axes in which the relevant self-alignment property does not apply (such as the block axis in Block Layout, or the main axis in Flex Layout), stretch-fit sizing still has the effect of causing the box to attempt to fill its containing block, invoking the percentage size calculations but applying that size to its margin box instead of the box indicated by box-sizing. For this purpose, auto margins are treated as zero, and furthermore, for block-level boxes in particular, if its block-start/block-end margin would be adjoining to its parent’s block-start/block-end margin if its parent’s sizing properties all had their initial values, then its block-start/block-end margin is treated as zero.

For example, given the following HTML representing two block boxes:

<div class="outer">
  <div class="inner"></div>
</div>

In the following case, the outer height of the inner box will exactly match the height of the outer box (200px), but its inner height will be 20px less, to account for its margins.

.outer { height: 200px; border: solid; }
.inner { height: stretch; margin: 10px; }

In the following case, the height of the inner box will exactly match the height of the outer box (200px). The top margins will collapse, but the bottom margins do not collapse (because the bottom margin of a box is not adjoining to the bottom margin of a parent with a non-auto height, see CSS 2.1 §8.3.1 Collapsing margins), and therefore the inner box’s bottom margin will be truncated.

.outer { height: 200px; margin: 0; }
.inner { height: stretch; margin: 10px; }

7.2. Contain-fit Sizing: stretching while maintaining an aspect ratio

Contain-fit sizing essentially applies stretch-fit sizing, but reduces the size of the box in one axis to maintain the box’s intrinsic aspect ratio, similar to the contain keyword of the object-fit and background-size properties.

First, a target rectangle is determined:

The initial target rectangle is the size of the box’s containing block, with any indefinite size assumed as infinity. If both dimensions are indefinite, the initial target rectangle is set to match the outer edges of the box were it stretch-fit sized.
Next, if the box has a non-none max-width or max-height, the target rectangle is clamped in the affected dimension to less than or equal to the “maximum size” of the box’s margin box, i.e. the size its margin box would be if the box was sized at its max-width/height. (Note that, consistent with normal box-sizing rules, this “maximum size” is floored by the effects of the box’s min-width/min-height.)
Last, the target rectangle is reduced in one dimension by the minimum necessary for it to match the box’s intrinsic aspect ratio.

The contain-fit size in each dimension is the size that would result from stretch-fitting into the target rectangle.

Copy whatever stretch-fit ends up doing wrt margin collapsing.

If there is a minimum size in one dimension that would cause overflow of the target rectangle if the aspect ratio were honored, do we honor the aspect ratio or skew the image? If the former, we need a step similar to #2 that applies the relevant minimums.

7.3. Percentage Sizing

…

Changes

Additions Since Level 3

Added stretch, fit-content, and contain keywords for sizing properties.
Added aspect-ratio property.
Added contain-intrinsic-size property.

Acknowledgments

Special thanks go to Aaron Gustafson, L. David Baron for their contributions to this module.

Privacy and Security Considerations

This specification introduces no new privacy or security considerations.

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:

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

A style sheet is conformant to this specification 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 this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification 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 this specification 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.

Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.

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

Implementations of Unstable and Proprietary Features

Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.

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.