CSS Box Model Module Level 3
CSS Box Model Module Level 3
This version:
https://www.w3.org/TR/2020/CR-css-box-3-20201222/
Latest published version:
https://www.w3.org/TR/css-box-3/
Editor's Draft:
https://drafts.csswg.org/css-box-3/
Previous Versions:
https://www.w3.org/TR/2020/WD-css-box-3-20201028/
Issue Tracking:
CSSWG Issues Repository
CSSWG GitHub
Editor:
Elika J. Etemad / fantasai (Invited Expert)
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 specification describes the margin and padding properties, which create spacing in and around a
CSS box.
CSS is a language for describing the rendering of structured documents (such as HTML and XML) on
screen, on paper, etc.
This document was published by the CSS Working Group as a Candidate Recommendation
Snapshot. Publication as a Candidate Recommendation does not imply endorsement by the W3C
Membership. A Candidate Recommendation Snapshot has received wide review and is intended to
gather implementation experience. This document is intended to become a W3C Recommendation; it
will remain a Candidate Recommendation at least until 22 February 2021 to gather additional
feedback.
Please send feedback by filing issues in GitHub (preferred), including the spec code “css-box” in the
title, like this: “[css-box] …summary of comment…”. All issues and comments are archived.
Alternately, feedback can be sent to the (archived) public mailing list [email protected].
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.
The following features are at-risk, and may be dropped during the CR period:
applicability of ‘margin’, ‘padding’ and their longhands to ruby base containers and ruby
annotation containers
“At-risk” is a W3C Process term-of-art, and does not necessarily imply that the feature is in danger of
being dropped or delayed. It means that the WG believes the feature may have difficulty being
interoperably implemented in a timely manner, and marking it as such allows the WG to drop the
feature if necessary when transitioning to the Proposed Rec stage, without having to publish a new
Candidate Rec without the feature first.
Table of Contents
1 Introduction
1.1 Value Definitions
1.2 Module Interactions
2 The CSS Box Model
2.1 Box-edge Keywords
3 Margins
3.1 Page-relative (Physical) Margin Properties: the ‘margin-top’, ‘margin-right’,
‘margin-bottom’, and ‘margin-left’ properties
3.2 Margin Shorthand: the ‘margin’ property
4 Padding
4.1 Page-relative (Physical) Padding Properties: the ‘padding-top’, ‘padding-right’,
‘padding-bottom’, and ‘padding-left’ properties
4.2 Padding Shorthand: the ‘padding’ property
5 Borders
Conformance
Document conventions
Conformance classes
Partial implementations
Implementations of Unstable and Proprietary Features
Non-experimental implementations
CR exit criteria
Index
Terms defined by this specification
Terms defined by reference
References
Normative References
Informative References
Property Index
§ 1. Introduction
This subsection is not normative.
CSS describes how each element and each string of text in a source document is laid out by
transforming the document tree into a set of boxes, whose size, position, and stacking level on the
canvas depend on the values of their CSS properties.
Note: CSS Cascading and Inheritance describes how properties are assigned to elements in the box
tree, while CSS Display 3 §1 Introduction describes how the document tree is transformed into the
box tree.
Each CSS box has a rectangular content area, a band of padding around the content, a border around
the padding, and a margin outside the border. The sizing properties [css-sizing-3], together with
various other properties that control layout, define the size of the content area. The box styling
properties—‘padding’ and its longhands, ‘border’ and its longhands, and ‘margin’ and its longhands—
define the sizes of these other areas.
Margins and padding are defined in this module. Borders are similarly defined in [css-backgrounds-3].
Note: This module only defines the physical per-side longhand properties. Additional, flow-
relative longhand properties are defined in [css-logical-1]. Note that both sets of longhand
properties control the same margins/padding: they are just different ways of indexing each side.
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.
This module replaces the definitions of the margin and padding properties defined in [CSS2] sections
8.1, 8.2, 8.3 (but not 8.3.1), and 8.4.
All properties in this module apply to the ‘::first-line’ and ‘::first-letter’ pseudo-elements.
The margin, border, and padding can be broken down into top, right, bottom, and left segments, each
of which can be controlled independently by its corresponding property.
The perimeter of each of the four areas (content, padding, border, and margin) is called an edge, and
each edge can be broken down into a top, right, bottom, and left side. Thus each box has four edges
each composed of four sides:
The background of the content, padding, and border areas of a box is specified by its ‘background’
properties. The border area can additionally be painted with a border style using the ‘border’
properties. Margins are always transparent. See [css-backgrounds-3].
When a box fragments—is broken, as across lines or across pages, into separate box fragments—each
of its boxes (content box, padding box, border box, margin box) also fragments. How the
content/padding/border/margin areas react to fragmentation is specified in [css-break-3] and controlled
by the ‘box-decoration-break’ property.
The following CSS keywords are defined for use in properties (such as ‘transform-box’ and
‘background-clip’) that need to refer to various box edges:
‘content-box’
Refers to the content box or content edge. (In an SVG context, treated as ‘fill-box’.)
‘padding-box’
Refers to the padding box or padding edge. (In an SVG context, treated as ‘fill-box’.)
‘border-box’
Refers to the border box or border edge. (In an SVG context, treated as ‘stroke-box’.)
‘margin-box’
Refers to the margin box or margin edge. (In an SVG context, treated as ‘stroke-box’.)
‘fill-box’
Refers to the object bounding box or its edges. (In a CSS box context, treated as ‘content-box’.)
‘stroke-box’
Refers to the stroke bounding box or its edges. (In a CSS box context, treated as ‘border-box’.)
‘view-box’
Refers to the nearest SVG viewport element’s origin box, which is a rectangle with the width and
height of the initial SVG user coordinate system established by the viewBox attribute for that
element, positioned such that its top left corner is anchored at the coordinate system origin. (In a
CSS box context, treated as ‘border-box’.)
Note: When the viewBox includes non-zero min-x or min-y offsets, this origin box does not
actually correspond to the visible region rectangle defined by the viewBox!
§ 3. Margins
Margins surround the border edge of a box, providing spacing between boxes. The margin properties
specify the thickness of the margin area of a box. The ‘margin’ shorthand property sets the margin for
all four sides while the margin longhand properties only set their respective side. This section defines
the physical ‘margin’ longhands. (Additional flow-relative ‘margin’ longhands are defined in
[css-logical-1].)
Note: Adjoining margins in block layout can collapse. See CSS2§8.3.1 Collapsing Margins for
details. Also, margins adjoining a fragmentation break are sometimes truncated. See CSS
Fragmentation 3 §5.2 Adjoining Margins at Breaks for details.
Applies to: all elements except internal table elements, ruby base containers, and ruby
annotation containers
Inherited: no
These properties set the top, right, bottom, and left margin of a box, respectively.
Negative values for margin properties are allowed, but there may be implementation-specific limits.
Name: ‘margin’
Value: <'margin-top'>{1,4}
Initial: 0
Applies to: all elements except internal table elements, ruby base containers, and ruby
annotation containers
Inherited: no
If there is only one component value, it applies to all sides. If there are two values, the top and bottom
margins are set to the first value and the right and left margins are set to the second. If there are three
values, the top is set to the first value, the left and right are set to the second, and the bottom is set to
the third. If there are four values they apply to the top, right, bottom, and left, respectively.
EXAMPLE 1
The following code demonstrates some possible ‘margin’ declarations.
The last rule of the example above is equivalent to the example below:
body {
margin-top: 1em;
margin-right: 2em;
margin-bottom: 3em;
margin-left: 2em; /* copied from opposite side (right) */
}
§ 4. Padding
Padding is inserted between the content edge and the padding edge of a box, providing spacing
between the content and the border. The padding properties specify the thickness of the padding area
of a box. The ‘padding’ shorthand property sets the padding for all four sides while the padding
longhand properties only set their respective side. This section defines the physical ‘padding’
longhands. (Additional flow-relative ‘padding’ longhands are defined in [css-logical-1].)
Note: Backgrounds specified on the box are by default laid out and painted within the padding
edges. (They are additionally painted underneath the border, in the border area.) This behavior can
be adjusted using the ‘background-origin’ and ‘background-clip’ properties.
Value: <length-percentage>
Initial: 0
Applies to: all elements except: internal table elements other than table cells, ruby base
containers, and ruby annotation containers
Inherited: no
These properties set the top, right, bottom, and left padding of a box, respectively.
Name: ‘padding’
Value: <'padding-top'>{1,4}
Initial: 0
Applies to: all elements except: internal table elements other than table cells, ruby base
containers, and ruby annotation containers
Inherited: no
If there is only one component value, it applies to all sides. If there are two values, the top and bottom
padding are set to the first value and the right and left padding are set to the second. If there are three
values, the top is set to the first value, the left and right are set to the second, and the bottom is set to
the third.
EXAMPLE 2
The following code demonstrates some possible ‘padding’ declarations.
The last rule of the example above is equivalent to the example below:
body {
padding-top: 1em;
padding-right: 2em;
padding-bottom: 3em;
padding-left: 2em; /* copied from opposite side (right) */
}
§ 5. Borders
Borders fill the border area, to visually delineate the edges of the box, The border properties specify
the thickness of the border area of a box, as well as its drawing style and color. See
[css-backgrounds-3] for the definition of these properties, including their physical longhands.
(Additional flow-relative border longhands are defined in [css-logical-1].)
Defining the non-applicability of ‘margin’, ‘padding’ and their longhands to ruby base containers
and ruby annotation containers (at risk).
Providing a centralized common definition of keywords that reference the various box edges for
use in properties defined outside this spec (e.g. ‘background-clip’) to avoid repetition (and the
resulting inevitable synchronization errors).
§ 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 3
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:
§ 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.
§ 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.
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
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
[email protected] mailing list.
§ CR exit criteria
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:
The specification will remain Candidate Recommendation for at least six months.
§ Index
§ Terms defined by this specification
margin-top, in §3.1
background box-decoration-break
§ References
§ Normative References
[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-BREAK-4]
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 4. 18 December 2018. WD.
URL: https://www.w3.org/TR/css-break-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-DISPLAY-3]
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. 18 December 2020. CR. URL:
https://www.w3.org/TR/css-display-3/
[CSS-PSEUDO-4]
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 25
February 2019. WD. URL: https://www.w3.org/TR/css-pseudo-4/
[CSS-RUBY-1]
Elika Etemad; et al. CSS Ruby Layout Module Level 1. 29 April 2020. WD. URL:
https://www.w3.org/TR/css-ruby-1/
[CSS-SIZING-3]
Tab Atkins Jr.; Elika Etemad. CSS Box Sizing Module Level 3. 18 December 2020. WD. URL:
https://www.w3.org/TR/css-sizing-3/
[CSS-TRANSFORMS-1]
Simon Fraser; et al. CSS Transforms Module Level 1. 14 February 2019. CR. URL:
https://www.w3.org/TR/css-transforms-1/
[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. 11 November 2020. 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/CSS21/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[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
[SVG2]
Amelia Bellamy-Royds; et al. Scalable Vector Graphics (SVG) 2. 4 October 2018. CR. URL:
https://www.w3.org/TR/SVG2/
§ Informative References
[CSS-BREAK-3]
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 3. 4 December 2018. CR.
URL: https://www.w3.org/TR/css-break-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/
§ Property Index
Anim-
Canonical Computed
Name Value Initial Applies to Inh. %ages ation
order value
type
refer to
all elements except internal by
logical see
<'margin- table elements, ruby base computed per
‘margin’ 0 no width of individual
top'>{1,4} containers, and ruby value grammar
containing properties
annotation containers type
block
the
refer to keyword
all elements except internal by
<length- logical auto or a
‘margin- table elements, ruby base computed per
percentage> 0 no width of computed
bottom’ containers, and ruby value grammar
| auto containing <length-
annotation containers type
block percentage>
value
the
refer to keyword
all elements except internal by
<length- logical auto or a
‘margin- table elements, ruby base computed per
percentage> 0 no width of computed
left’ containers, and ruby value grammar
| auto containing <length-
annotation containers type
block percentage>
value
the
refer to keyword
all elements except internal by
<length- logical auto or a
‘margin- table elements, ruby base computed per
percentage> 0 no width of computed
right’ containers, and ruby value grammar
| auto containing <length-
annotation containers type
block percentage>
value
Anim-
Canonical Computed
Name Value Initial Applies to Inh. %ages ation
order value
type
the
refer to keyword
all elements except internal by
<length- logical auto or a
‘margin- table elements, ruby base computed per
percentage> 0 no width of computed
top’ containers, and ruby value grammar
| auto containing <length-
annotation containers type
block percentage>
value