9 The box model

9.1 Introduction to the box model

The CSS box model describes the box rendering object. This object is characterized in particular by three groups of properties: margin, padding, and border, described below.

For information on the layout of boxes, please consult the section on the visual flow model.

The page box is a special kind of box which is described in detail on the section on paged media.

9.2 Box dimensions

Each box has a core content area (e.g., text, an image, etc.) and optional surrounding padding, border and margin areas. The following diagram illustrates how these areas relate and defines more precise terminology used to describe pieces of margin, border, and padding:

The width (resp., height) of the box is given by the sum of the content width (resp., height), the padding, the border, and the margin. The size of the margin, border and padding are set with the margin, padding, and border properties, respectively.

The width of the element is the width of the content, i.e., the distance between left inner edge and right inner edge. The height of the element is the height of the content, i.e., the distance from inner top to inner bottom.

The outer edge is the edge of an element including its padding, border, and margin. The inner edge is the edge of the content only, inside any padding, border or margin.

The top is the top of the object including any padding, border and margin; it is only defined for inline and floating elements, not for non-floating block-level elements. The inner top is the top of the content, inside any padding, border or margin. The bottom is the bottom of the element, outside any padding border and margin; it is only defined for inline and floating elements, not for non-floating block-level elements. The inner bottom is the bottom of the element, inside any padding, border and margin.

In the following sections, we define the properties that allow authors to set margins, padding, and borders. There are no properties to set the color of margins and padding; margins are always transparent and padding areas always uses the background of the element itself.

9.3 Margin properties: 'margin-top', 'margin-right', 'margin-bottom', 'margin-left', and 'margin'

Margin properties set the margin of an element. The 'margin' property sets the border for all four sides while the other margin properties only set their respective side.

Values for <margin-width>  

The properties defined in this section refer to the <margin-width> value type, whose possible values may be:

<length> | <percentage> | auto

Negative values for margin properties are allowed, but there may be implementation-specific limits.

Percentage values for margin properties refer to the width of the containing block.

This property sets the top margin of an element. It applies to replaced and block-level elements.

  H1 { margin-top: 2em }

This property sets the right margin of an element:

  H1 { margin-right: 12.3% }

This property sets the bottom margin of an element. It applies to replaced and block-level elements.

  H1 { margin-bottom: 3px }

This property sets the left margin of an element:

  H1 { margin-left: 2em }

The 'margin' property is a shorthand property for setting 'margin-top', 'margin-right' 'margin-bottom' and 'margin-left' at the same place in the style sheet.

If four length values are specified they apply to top, right, bottom and left respectively. If there is only one value, it applies to all sides, if there are two or three, the missing values are taken from the opposite side.

  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) */
  }

9.4 Padding properties: 'padding-top', 'padding-right', 'padding-bottom', 'padding-left', and 'padding'

The padding properties describe how much space to insert between the border and the content (e.g., text or image). The 'padding' property sets the padding for all four sides while the other padding properties only set their respective side.

9.4.1 Values for <padding-width> 

The properties defined in this section refer to the <padding-width> value type, whose possible values may be:

<length> | <percentage>

Unlike margin properties, values for padding values cannot be negative.

Like margin properties, percentage values for padding properties refer to the width of the containing block.

This property sets the top padding of an element.

  BLOCKQUOTE { padding-top: 0.3em }

This property sets the right padding of an element.

  BLOCKQUOTE { padding-right: 10px }

This property sets the bottom padding of an element.

  BLOCKQUOTE { padding-bottom: 2em }

This property sets the left padding of an element.

  BLOCKQUOTE { padding-left: 20% }

The 'padding' property is a shorthand property for setting 'padding-top', 'padding-right', 'padding-bottom', and 'padding-left' at the same place in the style sheet.

If four values are specified they apply to top, right, bottom and left respectively. If there is only one value, it applies to all sides, if there are two or three, the missing values are taken from the opposite side.

The surface of the padding area is set with the 'background' property:

  H1 { 
    background: white; 
    padding: 1em 2em;
  } 

9.5 Border properties

The border properties set the borders of an element. Each element has four borders, one on each side, that are defined by their width, color and style.

9.5.1 Border width: 'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width', and 'border-width'

Values for <border-width>  

The properties defined in this section refer to the <border-width> value type, whose possible values may be:

• 'thin' | 'medium' | 'thick' | <length>

The interpretation of the first three values depends on the user agent. The following must hold, however:

'thin' <='medium' <= 'thick'.

Furthermore, these widths must be constant throughout a document.

Border widths cannot be negative.

This property sets the width of an element's top border.

  H1 { border: solid thick red }
  P  { border: solid thick blue }

  H1 { border: solid 0.5em }

This property sets the width of an element's right border.

This property sets the width of an element's bottom border.

This property sets the width of an element's left border.

This property is a shorthand property for setting 'border-top-width', 'border-right-width', 'border-bottom-width', and 'border-left-width' at the same place in the style sheet.

There can be from one to four values, with the following interpretation:

• one value: all four border widths are set to that value
• two values: top and bottom border widths are set to the first value, right and left are set to the second
• three values: top is set to the first, right and left are set to the second, bottom is set to the third
• four values: top, right, bottom and left, respectively

  H1 { border-width: thin }                   /* thin thin thin thin */
  H1 { border-width: thin thick }             /* thin thick thin thick */
  H1 { border-width: thin thick medium }      /* thin thick medium thick */

9.5.2 Border color: 'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color', and 'border-color'

The 'border-color' property sets the color of the four borders. 'border-color' can have from one to four values, and the values are set on the different sides as for 'border-width' above.

If no color value is specified, the value of the 'color' property of the element itself will take its place:

  P { 
    color: black; 
    background: white; 
    border: solid;
  }

9.5.3 Border style: 'border-top-style', 'border-right-style', 'border-bottom-style', 'border-left-style', and 'border-style'

Values for <border-style>

The border style properties refer to the <border-style> value type which is defined as follows:

• none | dotted | dashed | solid | double | groove | ridge | inset | outset

The 'border-style' property sets the style of the four borders. It can have from one to four values, and the values are set on the different sides as for 'border-width' above.

  #xy34 { border-style: solid dotted }

Since the initial value of the border styles is 'none', no borders will be visible unless the border style is set.

The border styles mean:

none

no border is drawn (regardless of the 'border-width' property's value)

dotted

the border is a dotted line drawn on top of the background of the element

dashed

the border is a dashed line drawn on top of the background of the element

solid

the border is a solid line

double

the border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the value of 'border-width'.

groove

a 3D groove is drawn in colors based on the value of the 'color' property.

ridge

a 3D ridge is drawn in colors based on the value of the 'color' property.

inset

a 3D inset is drawn in colors based on the value of the 'color' property.

outset

a 3D outset is drawn in colors based on the value of the 'color' property.

UAs may interpret all of 'dotted', 'dashed', 'double', 'groove', 'ridge', 'inset' and 'outset' as 'solid'. See the section on conformance for details. 'border-top', 'border-bottom', 'border-right', 'border-left', and 'border'

This is a shorthand property for setting the width, style and color of an element's top border.

  H1 { border-bottom: thick solid red }

  H1 { border-bottom: thick solid }

Note that while the 'border-style' property accepts up to four values, this property only accepts one style value.

This is a shorthand property for setting the width, style and color of an element's bottom border. It behaves just like 'border-top'.

This is a shorthand property for setting the width, style and color of an element's right border. It behaves just like 'border-top'.

This is a shorthand property for setting the width, style and color of an element's left border. It behaves just like 'border-top'.

The 'border' property is a shorthand property for setting the same width, color and style on all four borders of an element.

Unlike the shorthand 'margin' and 'padding' properties, the 'border' property cannot set different values on the four borders. To do so, one or more of the other border properties must be used.

Note that while the 'border-width' property accepts up to four length values, this property only accepts one.

  P { border: solid red }
  P {
    border-top: solid red;
    border-right: solid red;
    border-bottom: solid red;
    border-left: solid red
  }

Since to some extent the properties have overlapping functionality, the order in which the rules are specified becomes important.

  BLOCKQUOTE {
    border-color: red;
    border-left: double
    color: black;
  }

Example of margins, padding, and borders

    <STYLE type="text/css">
      UL { 
        background: orange; 
        margin: 12px 12px 12px 12px
        padding: 3px 3px 3px 3px
                                    /* No borders set */
      }
      LI { 
        color: white;               /* text color is white */ 
        background: blue;           /* Content, padding will be blue */
        margin: 12px 12px 12px 12px
        padding: 12px 0px 12px 12px /* Note 0px padding right */
        list-style: none            /* no glyphs before a list item */
                                    /* No borders set */
      }
      LI.withborder {
        border-style: dashed;
        border-width: medium;       /* sets border width on all sides */
        border-color: green;
      }
    </STYLE>
    <UL>
      <LI>First element of list
      <LI class="withborder">Second element of list is longer
           to illustrate wrapping.
    </UL>

results in a document tree with (among other relationships) a UL element that has two LI children. According to the visual rendering model, the LI elements are laid out vertically (one after the other) and form the content of the UL.

The first of the following diagrams illustrates what this example would produce. The second illustrates the relationship between the margins, padding, and borders of the UL elements and those of its children LI elements.

Note that:

• The width of content for each LI element has not been specified by the 'width' property. Therefore, according to the rules of the box height calculations, the width allotted for the content of each LI element is the width of the parent element's (UL) content less the margins, padding, and border of the LI elements. The width of the UL element is determined by the width of its parent, not shown explicitly here.
• The height of each LI element's contents is determined by the height of the content. The height of the UL element's content is determined by the sum of the heights of the LI elements' content, plus LI margins, padding, and borders (see the section on box height calculations for details). Note that vertical margins between the LI boxes collapse.
• The initial border style is 'none', and this value must be changed for a border to be rendered. In the example above, only the second list-item element changes the border style.
• The right side padding of the LI elements has been set to zero width. The effect is apparent in the second illustration.
• The foreground color of the LI elements has been set to white for legibility against a blue background.
• The margins and padding of the LI elements are transparent (due to the initial value), so the background color of the UL elements (orange) shines through the transparent LI margins. However, the (blue) background color (blue) of the LI elements changes the color of the LI padding and content.
• Although padding and margin properties are not inherited, the LI elements are still offset by the UL margin.