CSS Box Sizing Module Level 4

W3C Working Draft, 20 October 2020

This version:
https://www.w3.org/TR/2020/WD-css-sizing-4-20201020/
Latest published version:
https://www.w3.org/TR/css-sizing-4/
Editor's Draft:
https://drafts.csswg.org/css-sizing-4/
Previous Versions:
https://www.w3.org/TR/2020/WD-css-sizing-4-20200526/
Issue Tracking:
CSSWG GitHub
Inline In Spec
GitHub Issues
Editors:
Tab Atkins (Google)
Elika J. Etemad / fantasai (Invited Expert)
Jen Simmons (Mozilla)
Suggest an Edit for this Spec:
GitHub Editor

Copyright © 2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules
apply.

Abstract
This module extends the CSS sizing properties with keywords that represent content-based "intrinsic"
sizes and context-based "extrinsic" sizes, allowing CSS to more easily describe boxes that fit their
content or fit into a particular layout context. This is a delta spec over CSS Sizing Level 3.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on
screen, on paper, etc.
Status of this document
This section describes the status of this document at the time of its publication. Other documents may
supersede this document. A list of current W3C publications and the latest revision of this technical
report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft
document and may be updated, replaced or obsoleted by other documents at any time. It is
inappropriate to cite this document as other than work in progress.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the
text “css-sizing” in the title, preferably like this: “[css-sizing] …summary of comment…”. All issues
and comments are archived, and there is also a historical archive.

This document was produced by the CSS Working Group.

This document was produced by a group operating under the 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.

This document is governed by the 15 September 2020 W3C Process Document.

Table of Contents

1 Introduction
1.1 Module interactions
1.2 Value Definitions

2 Terminology

3 Specifying Box Sizes

3.1 Sizing Properties
3.2 New Sizing Values: the ‘stretch’, ‘fit-content’, and ‘contain’ keywords

4 Aspect Ratios
4.1 Intrinsic Aspect Ratios: the ‘aspect-ratio’ property
4.1.1 Cyclic Aspect-Ratio Calculations
4.1.2 Automatic Content-based Minimum Sizes
5 Intrinsic Size Determination
5.1 Overriding Contained Intrinsic Sizes: the ‘contain-intrinsic-size’ property
5.1.1 Interaction With ‘overflow: auto’

6 Intrinsic Size Contributions

7 Extrinsic Size Determination

7.1 Stretch-fit Sizing: filling the containing block
7.2 Contain-fit Sizing: stretching while maintaining an aspect ratio
7.3 Percentage Sizing

Changes
Recent Changes
Additions Since Level 3

Acknowledgments

Privacy and Security Considerations

Conformance
Document conventions
Conformance classes
Requirements for Responsible Implementation of CSS
Partial Implementations
Implementations of Unstable and Proprietary Features
Implementations of CR-level Features

Index
Terms defined by this specification
Terms defined by reference

References
Normative References
Informative References

Property Index

Issues Index
§ 1. Introduction

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

ISSUE 2 CSS Sizing 3 §2 Terminology

§ 3. Specifying Box Sizes

ISSUE 3 CSS Sizing 3 §3 Specifying Box Sizes

§ 3.1. Sizing Properties

ISSUE 4 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 stretch | fit-content | contain

values:

‘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
Images often have an intrinsic 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. 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 specified keyword or a pair of numbers

value:

Canonical per grammar

order:

Animation discrete
type:

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.

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

ISSUE 5 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.
When a box has a preferred aspect ratio, its 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. The opposite axis (on which the ratio-dependent axis size depends) is the ratio-
determining axis.

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.

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

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

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.
EXAMPLE 1
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;
}

EXAMPLE 2
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 number) / 1) {

iframe {
aspect-ratio: attr(width number) / attr(height number);
width: 100%;
height: auto;
}
}
 EXAMPLE 3
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 §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”.

§ 4.1.1. Cyclic Aspect-Ratio Calculations

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.
 EXAMPLE 4
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.

§ 4.1.2. 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.
EXAMPLE 5
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;
}
 +----------+ +----------+ +----------+
| ~~~~~~~~ | | ~~~~~~~~ | | ~~~~~~~~ |
| ~~~~~~~~ | | ~~~~~~~~ | | ~~~~~~~~ |
| ~~~~~~~ | | ~~~~~~~~ | | ~~~~~~~~ |
| | | ~~~ | | ~~~~~~~~ |
+----------+ +----------+ +-~~~~~~~~-+
~~~~~~

EXAMPLE 6
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 as specified, with <length> values computed

value:
 Canonical per grammar
order:

Animation by computed value type

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.

EXAMPLE 7
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.
 EXAMPLE 8
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

ISSUE 6 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), 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.
EXAMPLE 9
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 §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; }

EXAMPLE 10
Similarly, ‘width: stretch’ causes the box to fill its container, being 20px narrower than the width
of "some more text" (due to the 10px margin):

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

.outer { float: left; margin: 0; }

.inner { width: stretch; margin: 10px; }
 EXAMPLE 11
On the other hand, in this example the container’s height is indefinite, which would cause a
percentage height on the child to behave as auto, so ‘height: stretch’ behaves as auto as well.

.outer { height: auto; 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:

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 intrinsic aspect ratio.

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

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

ISSUE 8 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
§ Recent Changes

Significant changes since the 26 May 2020 First Public Working Draft include:

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 intrinsic dimension determines the
other dimension. (Issue 5306)

If a replaced element’s only intrinsic dimension is an intrinsic width or an intrinsic height,

giving it a preferred aspect ratio also gives it an intrinsic 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:

EXAMPLE 12

This is an example of an informative example.

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:

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

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.

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

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

§ Index
§ Terms defined by this specification

aspect-ratio, in §4.1 contain, in §3.2

auto, in §4.1 contain-fit sizing, in §7.1

auto && <ratio>, in §4.1 contain-intrinsic-size, in §5.1

 explicit intrinsic inner size, in §5.1 <ratio>, in §4.1
fit-content, in §3.2 ratio-dependent axis, in §4.1
<length>{2}, in §5.1 ratio-determining axis, in §4.1

none, in §5.1 stretch, in §3.2

preferred aspect ratio, in §4.1

§ Terms defined by reference

[css-align-3] defines the following terms: [css-display-3] defines the following terms:
alignment container block box

justify-self block-level box

self-alignment properties containing block

start formatting context

stretch (for justify-self) inline box

non-replaced
[css-backgrounds-3] defines the following
replaced element
terms:
background-size [css-flexbox-1] defines the following terms:
[css-box-4] defines the following terms: content

content box cross size

margin flex item

margin box [css-images-3] defines the following terms:

contain
[css-cascade-4] defines the following terms:
computed value intrinsic aspect ratio

initial value intrinsic dimensions

object-fit
[CSS-CONTAIN-1] defines the following
terms: [css-logical-1] defines the following terms:
size containment block-size
inline-size
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: [CSS-VALUES-3] defines the following terms:
absolutely-positioned <length>

[css-sizing-3] defines the following terms: [css-values-4] defines the following terms:
auto <ratio>
automatic minimum size css-wide keywords
automatic size {a,b}
behave as auto |
behaves as auto ||
box-sizing [css-writing-modes-4] defines the following
definite terms:
height block axis
inner height block size
intrinsic size contribution horizontal writing mode
max-content inline size
max-content contribution [CSS2] defines the following terms:
maximum size max-height
min-content max-width
min-content contribution min-height
min-content size min-width
minimum size
[CSS3COL] defines the following terms:
none
column-width
outer height
[HTML] defines the following terms:
preferred size
iframe
sizing property
stretch-fit size
width

§ References
§ Normative References

[CSS-ALIGN-3]
Elika Etemad; Tab Atkins Jr.. CSS Box Alignment Module Level 3. 21 April 2020. WD. URL:
https://www.w3.org/TR/css-align-3/
[CSS-BACKGROUNDS-3]
 Bert Bos; Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 17
October 2017. CR. URL: https://www.w3.org/TR/css-backgrounds-3/
[CSS-BOX-4]
Elika Etemad. CSS Box Model Module Level 4. 21 April 2020. WD. URL:
https://www.w3.org/TR/css-box-4/
[CSS-CASCADE-4]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. 18 August 2020. WD.
URL: https://www.w3.org/TR/css-cascade-4/
[CSS-CONTAIN-1]
Tab Atkins Jr.; Florian Rivoal. CSS Containment Module Level 1. 21 November 2019. REC.
URL: https://www.w3.org/TR/css-contain-1/
[CSS-DISPLAY-3]
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. 19 May 2020. CR. URL:
https://www.w3.org/TR/css-display-3/
[CSS-IMAGES-3]
Tab Atkins Jr.; Elika Etemad; Lea Verou. CSS Images Module Level 3. 10 October 2019. CR.
URL: https://www.w3.org/TR/css-images-3/
[CSS-LOGICAL-1]
Rossen Atanassov; Elika Etemad. CSS Logical Properties and Values Level 1. 27 August 2018.
WD. URL: https://www.w3.org/TR/css-logical-1/
[CSS-OVERFLOW-3]
David Baron; Elika Etemad; Florian Rivoal. CSS Overflow Module Level 3. 3 June 2020. WD.
URL: https://www.w3.org/TR/css-overflow-3/
[CSS-SIZING-3]
Tab Atkins Jr.; Elika Etemad. CSS Intrinsic & Extrinsic Sizing Module Level 3. 22 May 2019.
WD. URL: https://www.w3.org/TR/css-sizing-3/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 6 June 2019. CR. URL:
https://www.w3.org/TR/css-values-3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 31 January 2019. WD.
URL: https://www.w3.org/TR/css-values-4/
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. 30 July 2019. CR. URL:
https://www.w3.org/TR/css-writing-modes-4/
[CSS2]
 Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011.
REC. URL: https://www.w3.org/TR/CSS2/
[CSS3COL]
Håkon Wium Lie; Florian Rivoal; Rachel Andrew. CSS Multi-column Layout Module Level 1.
15 October 2019. WD. URL: https://www.w3.org/TR/css-multicol-1/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best
Current Practice. URL: https://tools.ietf.org/html/rfc2119

§ Informative References

[CSS-FLEXBOX-1]
Tab Atkins Jr.; et al. CSS Flexible Box Layout Module Level 1. 19 November 2018. CR. URL:
https://www.w3.org/TR/css-flexbox-1/
[CSS-POSITION-3]
Elika Etemad; et al. CSS Positioned Layout Module Level 3. 19 May 2020. WD. URL:
https://www.w3.org/TR/css-position-3/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL:
https://html.spec.whatwg.org/multipage/

§ Property Index
Anim-
Canonical Computed
Name Value Initial Applies to Inh. %ages ation
order value
type

specified
‘aspect- auto || all elements except inline boxes per keyword or a
auto no n/a discrete
ratio’ <ratio> and internal ruby or table boxes grammar pair of
numbers

as specified,
by
‘contain- none | with
computed per
intrinsic- <length> none elements with size containment no n/a <length>
value grammar
size’ {1,2} values
type
computed

§ Issues Index
ISSUE 1 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. ↵

ISSUE 2 CSS Sizing 3 §2 Terminology ↵

ISSUE 3 CSS Sizing 3 §3 Specifying Box Sizes ↵

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

ISSUE 5 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. ↵

ISSUE 6 CSS Sizing 3 §5 Extrinsic Size Determination ↵

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

ISSUE 8 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. ↵