Title: CSS Box Model Module Level 3
Shortname: css-box
Level: 3
Status: ED
Work Status: Refining
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/2020/WD-css-box-3-20201028/
Abstract: This specification describes the margin and padding properties, which create spacing in and around a CSS box.
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Ignored Terms: internal table elements, block layout
At risk: applicability of 'margin', 'padding' and their longhands to [=ruby base containers=] and [=ruby annotation containers=]
Issue Tracking: CSSWG GitHub https://github.com/w3c/csswg-drafts/issues

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

Value Definitions

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.

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 <{svg/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 <{svg/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 <{svg/viewBox}>!

		<> = content-box | padding-box | border-box
		<> = content-box | padding-box | border-box | margin-box
		<> = content-box | padding-box | border-box | fill-box | stroke-box
		<> = content-box | padding-box | border-box | fill-box | stroke-box | view-box
	

		Name: margin-top, margin-right, margin-bottom, margin-left
		Value: <> | auto
		Initial: 0
		Applies to: all elements except internal table elements, [=ruby base containers=], and [=ruby annotation containers=]
		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, [=ruby base containers=], and [=ruby annotation containers=]
		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: padding-top, padding-right, padding-bottom, padding-left
		Value: <>
		Initial: 0
		Applies to: all elements except: internal table elements other than table cells, [=ruby base containers=], and [=ruby annotation containers=]
		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, [=ruby base containers=], and [=ruby annotation containers=]
		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) */
			}
		

• Adapting the prose slightly to account for vertical writing modes.
• Cross-linking to relevant concepts in [[css-break-3]] and [[css-backgrounds-3]].
• Defining the non-applicability of 'margin', 'padding' and their longhands to [=ruby base containers=] and [=ruby annotation containers=] (at risk).
• Providing a [[#keywords|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).