↑ →

Status of this document

Table of Contents

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

If the box has no preferred aspect ratio, applies stretch-fit sizing.

4. Aspect Ratios

Images often have a natural aspect ratio, which the CSS layout algorithms attempt to preserve as they resize the element.

The aspect-ratio property allows specifying this behavior for non-replaced elements, and for altering the effective aspect ratio of replaced elements.

4.1. Preferred Aspect Ratios: the aspect-ratio property

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.

If the <ratio> is degenerate, the property instead behaves as auto.

If the <ratio> is degenerate, the property instead behaves as auto.

Note: Having a preferred aspect ratio does not make a box into a replaced element; layout rules specific to replaced elements do not generally 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), even if it has a preferred aspect ratio

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.

<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;}

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

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

If a replaced element’s only natural dimension is a natural width or a natural height, giving it a preferred aspect ratio also gives it an natural height or width, whichever was missing, by transferring the existing size through the preferred aspect ratio.

4.2. Effects of Preferred Aspect Ratio on Automatic Sizes

When a box has a preferred aspect ratio, its automatic sizes are calculated the same as for a replaced element with a natural aspect ratio and no natural size 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. The opposite axis (on which the ratio-dependent axis size depends) is the ratio-determining axis.

Note: A preferred aspect ratio only ever has an effect if at least one of the box’s sizes is automatic. If neither width nor height is an automatic size, it can have no effect on its preferred sizes.

When we move all the sizing information here, rather than crowbar-ing our way into 2.1, then the core principle here is just: the resolved preferred size in the ratio-determining axis (before applying min/max) gets transferred thru the ratio. Min/max constraints get transferred afterwards, and then applied to each axis independently without regards to aspect-ratio.

4.2.1. Margin-collapsing

For the purpose of margin collapsing (CSS 2 §8.3.1 Collapsing margins), if the block axis is the ratio-dependent axis, it is not considered to have a computed block-size of auto.

4.3. 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 capped by its maximum size.

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

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

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

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

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

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

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

4.4. Min/Max Size Transfers

Sizing constraints in either axis (the origin axis) are transferred through the preferred aspect ratio to the other axis (the destination axis) as follows:

• First, any definite minimum size is converted and transferred from the origin to destination axis. This transferred minimum is capped by any definite preferred or maximum size in the destination axis.

• Then, any definite maximum size is converted and transferred from the origin to destination. This transferred maximum is floored by any definite preferred or minimum size in the destination axis as well as by the transferred minimum, if any.

Note: The basic principle is that sizing constraints transfer through the aspect-ratio to the other side to preserve the aspect ratio to the extent that they can without violating any sizes specified explictly on that affected axis.

<divid=containerstyle="height: 100px; float: left;"><divid=itemstyle="height: 100%; aspect-ratio: 1/1;">content</div></div>

<divid=containerstyle="height: auto; float: left;"><divid=itemstyle="height: 100%; aspect-ratio: 1/1;">content</div></div>

5. Intrinsic Size Determination

5.1. Intrinsic Sizes

CSS Sizing 3 §5.1 Intrinsic Sizes

5.2. Overriding Contained Intrinsic Sizes: the contain-intrinsic-* properties

These properties allow 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. For example, a grid container with one child of the specified size would still size according to the specified grid, usually ending up with a larger content size than specified.

Values are defined as:

The corresponding axis does not have an explicit intrinsic inner size.

The corresponding axis has an explicit intrinsic inner size of the specified <length>.

If an element has an explicit intrinsic inner size in an axis, then after laying out the element as normal for size containment, the size of the contents in that axis are instead treated as being the explicit intrinsic inner size instead of what was calculated in layout, and layout is performed again if necessary. (If it has an explicit intrinsic inner size in both axises, this implies the first layout can be skipped.)

These four properties are part of a logical property group.

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.

contain-intrinsic-size is a shorthand property that sets the contain-intrinsic-width and contain-intrinsic-height properties.

The first value represents the contain-intrinsic-width value, and the second represents the contain-intrinsic-height value. If only one value is given, it applies to both properties.

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

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

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

5.3. Intrinsic Size Contributions

CSS Sizing 3 §5.2 Intrinsic Contributions

5.4. Zeroing Min-Content Size Contributions: the min-intrinsic-sizing property

This property seriously needs some name bikeshedding.

This property defines whether the min-content contribution of a non-replaced box is “compressed” under certain circumstances. Values have the following meanings:

Note: This is the default behavior of most replaced elements.

*, ::before, ::after {min-intrinsic-size: zero-if-scroll;}

Note: The behavior of zero-if-scroll would have been a better default, but due to Web-compat, it cannot be the initial value. :(

The “compressed” min-content contributions is calculated by pretending the box were empty, except when factoring in sizing constraints imposed by explicit min-content, max-content, and fit-content values of the sizing properties.

6. Extrinsic Size Determination

CSS Sizing 3 §4 Extrinsic Size Determination

6.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), in cases where a percentage size in that axis would resolve to a definite value, a stretch-fit size causes the box to attempt to fill its containing block—behaving as 100% but applying the resulting 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.

Note: Consequently, if neither stretch alignment applies nor percentage sizing can resolve, then the box will resolve to its automatic size.

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

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

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

<div class="outer">
  <div class="inner">text</div>
</div>
some more text

.outer { float: left; margin: 0; }
.inner { width: stretch; margin: 10px; }

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

6.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 preferred aspect ratio, similar to the contain keyword of the object-fit and background-size properties.

First, a target rectangle is determined:

1. 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.
2. 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.)
3. Last, the target rectangle is reduced in one dimension by the minimum necessary for it to match the box’s preferred 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.

6.3. Percentage Sizing

Changes

Recent Changes

• Define ratio-determining axis as a term.

• Define that min/max sizing constraints are transferred across an aspect-ratio, (Issue 5257)

  Additionally, sizing constraints in either axis (the origin axis) are transferred through the preferred aspect ratio to the other axis (the destination axis) as follows:

  • First, any definite minimum size is converted and transferred from the origin to destination axis. This transferred minimum is capped by any definite preferred or maximum size in the destination axis.

  • Then, any definite maximum size is converted and transferred from the origin to destination. This transferred maximum is floored by any definite preferred or minimum size in the destination axis as well as by the transferred minimum, if any.

  Note: The basic principle is that sizing constraints transfer through the aspect-ratio to the other side to preserve the aspect ratio to the extent that they can without violating any sizes specified explictly on that affected axis.

• Clarify that aspect-ratio on a replaced element with only one natural size determines the other dimension. (Issue 5306)

  If a replaced element’s only natural dimension is a natural width or a natural height, giving it a preferred aspect ratio also gives it a natural height or width, whichever was missing, by transferring the existing size through the preferred aspect ratio.

• Define that aspect-ratio inhibits margin self-collapsing (Issue 5328)

  For the purpose of margin collapsing (CSS 2 §8.3.1 Collapsing margins), if the block axis is the ratio-dependent axis, it is not considered to have a computed block-size of auto.

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:

Note, this is an informative note.

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

Conformance to this specification is defined for three 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.

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.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

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 [email protected] mailing list.

Index

Terms defined by this specification

Terms defined by reference

• [css-align-3] defines the following terms:
  • alignment container
  • justify-self
  • self-alignment properties
  • start
  • stretch (for justify-self)
• [css-backgrounds-3] defines the following terms:
  • background-size
• [css-box-4] defines the following terms:
  • content box
  • margin
  • margin box
• [css-cascade-5] defines the following terms:
  • computed value
  • initial value
• [css-contain-2] defines the following terms:
  • size containment
• [css-display-3] defines the following terms:
  • block box
  • block-level box
  • containing block
  • formatting context
  • inline box
  • non-replaced
  • replaced element
• [css-grid-2] defines the following terms:
  • grid container
• [css-images-3] defines the following terms:
  • natural aspect ratio
  • natural dimension
  • natural height
  • natural size
  • natural width
• [css-images-4] defines the following terms:
  • contain
  • object-fit
• [css-logical-1] defines the following terms:
  • block-size
  • inline-size
  • logical property group
  • max-block-size
  • max-inline-size
  • min-block-size
  • min-inline-size
• [css-overflow-3] defines the following terms:
  • overflow
  • scroll container
• [css-position-3] defines the following terms:
  • absolutely-positioned
• [css-sizing-3] defines the following terms:
  • automatic minimum size
  • automatic size
  • behave as auto
  • behaves as auto
  • box-sizing
  • definite
  • extrinsic sizing
  • height
  • inner height
  • intrinsic size contribution
  • max-content
  • maximum size
  • min-content
  • min-content contribution
  • min-content size
  • minimum size
  • outer height
  • preferred size
  • sizing property
  • stretch-fit size
  • width
• [CSS-VALUES-3] defines the following terms:
  • <length>
• [css-values-4] defines the following terms:
  • <ratio>
  • css-wide keywords
  • degenerate ratio
  • {a,b}
• [css-writing-modes-4] defines the following terms:
  • block axis
• [CSS2] defines the following terms:
  • max-height
  • max-width
  • min-height
  • min-width
• [CSS3COL] defines the following terms:
  • column-width
• [HTML] defines the following terms:
  • iframe

References

Normative References

Informative References

Property Index

Issues Index