Title: CSS Box Model Module Level 3
Shortname: css-box
Level: 3
Status: ED
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-box-3/
TR: https://www.w3.org/TR/css-box-3/
Previous Version: https://www.w3.org/TR/2018/WD-css-box-3-20180802/
Abstract: This specification describes the margin and padding properties, which create spacing in and around a CSS box. It may later be extended to include borders (currently described in [[css-backgrounds-3]]).
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Ignored Terms: internal table elements, block layout

spec:css-sizing-3; type:dfn; text:size

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#intro]] 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 defined in [[css-backgrounds-3]]. Note: This module originally contained the CSS Level 3 specification prose relating to box generation (now defined in [[css-display-3]]), the box model (defined here), as well as block layout (now only defined in [[CSS2]] Chapters 9 and 10). Since its maintenance was put aside during the development of CSS2.1, its prose was severely outdated by the time CSS2 Revision 1 was finally completed. Therefore, the block layout portion of the prose has been retired, to be re-synched to CSS2 and updated as input to a new Block Layout module at some point in the future. It is being split apart from this module and from the CSS Display Module both because of the practical concern that it would be a huge amount of work and also in recognition that CSS now has multiple layout models (Flex Layout, Grid Layout, Positioned Layout, and Table Layout, in addition to Block Layout) which each deserve their own parallel module.

Values

Module Interactions

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 CSS Box Model {#box-model} =================

Each box has a content area (which contains its content-- text, descendant boxes, an image or other replaced element content, etc.) and optional surrounding padding, border, and margin areas; the size of each area is specified by corresponding properties, and can be zero (or in the case of margins, negative). The following diagram shows how these areas relate and the terminology used to refer to the various parts of the box:

content edge or inner edge

The content edge surrounds the rectangle given by the width and height of the box, which often depend on the element's content and/or its containing block size. The four sides of the content edge together define the box's content box.

padding edge

The padding edge surrounds the box’s padding. If the padding has zero width on a given side, the padding edge coincides with the content edge on that side. The four sides of the padding edge together define the box's padding box, which contains both the content and padding areas.

border edge

The border edge surrounds the box’s border. If the border has zero width on a given side, the border edge coincides with the padding edge on that side. The four sides of the border edge together define the box's border box, which contains the box’s content, padding, and border areas.

margin edge or outer edge

The margin edge surrounds the box’s margin. If the margin has zero width on a given side, the margin edge coincides with the border edge on that side. The four sides of the margin edge together define the box's margin box, which contains the all of the box’s content, padding, border, and margin areas.

		Name: margin-top, margin-right, margin-bottom, margin-left
		Value: <> | auto
		Initial: 0
		Applies to: all elements except internal table elements
		Inherited: no
		Percentages: refer to logical width of containing block
		Computed value: the keyword ''margin/auto'' or a computed <> value
		Animation type: by computed value type
	

		Name: margin
		Value: <<'margin-top'>>{1,4}
		Initial: 0
		Applies to: all elements except internal table elements
		Inherited: no
		Percentages: refer to logical width of containing block
		Computed value: see individual properties
		Animation type: by computed value type
	

			body { margin: 2em }         /* all margins set to 2em */
			body { margin: 1em 2em }     /* top & bottom = 1em, right & left = 2em */
			body { margin: 1em 2em 3em } /* top=1em, right=2em, bottom=3em, left=2em */
		

			body {
			  margin-top: 1em;
			  margin-right: 2em;
			  margin-bottom: 3em;
			  margin-left: 2em; /* copied from opposite side (right) */
			}
		

		Name: margin-trim
		Value: none | in-flow | all
		Initial: none
		Applies to: [=block containers=], [=multi-column containers=]
		Inherited: no
		Percentages: N/A
		Computed value: keyword as specified
		Animation type: discrete
	

none

Margins are not trimmed by the container. Note: However, in block layout, child margins can collapse with their parent. See CSS2§8.3.1: Collapsing Margins.

in-flow

For in-flow boxes contained by this box, block-axis margins adjacent to the box’s edges are truncated to zero. It also truncates any margins collapsed with such a margin.

all

Trims the margins of in-flow boxes as for ''in-flow'', but also trims any float margin whose [=margin edge=] coincides with the container’s [=content edge=].

• The block-start margin of a block-level first child.
• The block-end margin of a block-level last child.
• Any margin collapsed with these margins.

• Discarding the [=block-start=] [=margin=] of any float whose [=block-start=] [=outer edge=] coincides with the [=block-start=] [=inner edge=] of the container.
• Discarding the [=inline-start=]/[=inline-end=] [=margin=] of an [=inline-start=]/[=inline-end=] float (or equivalent) whose [=outer edge=] on that side coincides with the [=inner edge=] of the container.
• Zeroing the [=inline-axis=] margins of a float for the purpose of calculating its [=intrinsic size contributions=] or its [=size=] in the container’s [=inline axis=].
• Trimming the [=block-end=] margins of a float to the extent necessary to prevent such a margin from extending the [=block size=] of a [=block formatting context root=].

		Name: padding-top, padding-right, padding-bottom, padding-left
		Value: <>
		Initial: 0
		Applies to: all elements except: internal table elements other than table cells
		Inherited: no
		Percentages: refer to logical width of containing block
		Computed value: a computed <> value
		Animation type: by computed value type
	

		Name: padding
		Value: <<'padding-top'>>{1,4}
		Initial: 0
		Applies to: all elements except: internal table elements other than table cells
		Inherited: no
		Percentages: refer to logical width of containing block
		Computed value: see individual properties
		Animation type: by computed value type
	

			body { padding: 2em }         /* all padding set to 2em */
			body { padding: 1em 2em }     /* top & bottom = 1em, right & left = 2em */
			body { padding: 1em 2em 3em } /* top=1em, right=2em, bottom=3em, left=2em */
		

			body {
			  padding-top: 1em;
			  padding-right: 2em;
			  padding-bottom: 3em;
			  padding-left: 2em; /* copied from opposite side (right) */
			}
		

• Adding the 'margin-trim' property.
• Adapting the prose slightly to account for vertical writing modes.