CSS Borders and Box Decorations Module Level 4

1. Introduction

The properties of this module deal with the decoration of the border area. It also defines decorations that can be applied to the box.

1.1. Module Interactions

This specification extends the parts related to borders and box decorations of CSS Backgrounds and Borders Module Level 3 [CSS3BG].

It provides specifications for the added corner-*-shape and border-shape properties, as well as logical shorthands for border-*-radius, box-shadow-* longhands, and partial borders via the border-limit and border-*-clip properties.

All properties in this module apply to the ::first-letter pseudo-element. The border-radius properties also apply to the ::first-line pseudo-element. The UA may (but is not required to) apply the border-image or box-shadow properties to ::first-line. The UA must not apply the border-color/style/width properties to ::first-line. [CSS2]

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. For example, combining with CSS Images allows for using CSS gradients as background-image or border-image values. [CSS-IMAGES-3]

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

The border can either be a predefined style (solid line, double line, dotted line, pseudo-3D border, etc.) or it can be an image. In the former case, various properties define the style (border-style), color (border-color), and thickness (border-width) of the border.

2.1. Line Colors: the border-color properties

These properties set the foreground color of the border specified by the border-style properties.

The stripes defined by <image-1D> follow the shape of the border on the side to which they apply, and are drawn in bands starting from the padding edge and progressing outwards. The border width at each point defines the total width of the stripes at that point.

.foo {
  border: 30px solid;
  border-color: stripes(dodgerblue, skyblue) stripes(yellow, gold) stripes(lightgreen, limegreen) stripes(indianred, orange);
}

border-color is a shorthand property for the four physical border-*-color properties. The four values set the top, right, bottom and left border, respectively. A missing left is the same as right, a missing bottom is the same as top, and a missing right is also the same as top. This is resolved individually for each list item.

The flow-relative properties border-block-start-color, border-block-end-color, border-inline-start-color, and border-inline-end-color correspond to the physical properties border-top-color, border-bottom-color, border-left-color, and border-right-color. The mapping depends on the element’s writing-mode, direction, and text-orientation.

These two shorthand properties set the border-block-start-color & border-block-end-color and border-inline-start-color & border-inline-end-color, respectively. The first value represents the start side color, and the second value represents the end side color. If only one value is given, it applies to both the start and end sides.

2.2. Line Patterns: the border-style properties

These properties control whether a border appears, and if it does what style it’s drawn in (if it is not overridden by a border image).

The flow-relative properties border-block-start-style, border-block-end-style, border-inline-start-style, and border-inline-end-style correspond to the physical properties border-top-style, border-bottom-style, border-left-style, and border-right-style. The mapping depends on the element’s writing-mode, direction, and text-orientation.

These two shorthand properties set the border-block-start-style & border-block-end-style and border-inline-start-style & border-inline-end-style, respectively. The first value represents the start side style, and the second value represents the end side style. If only one value is given, it applies to both the start and end sides.

border-style is a shorthand property for the four physical border-*-style properties. The four values set the top, right, bottom and left border, respectively. A missing left is the same as right, a missing bottom is the same as top, and a missing right is also the same as top. This is resolved individually for each list item.

The style is specified as a <line-style> keyword, where

<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

Values have the following meanings:

none

No border. Color and width are ignored (i.e., the border has width 0). Note this means that the initial value of border-image-width will also resolve to zero.

hidden

Same as none, but has different behavior in the border conflict resolution rules for border-collapsed tables [CSS2].

dotted

A series of round dots.

dashed

A series of square-ended dashes.

solid

A single line segment.

double

Two parallel solid lines with some space between them. (The thickness of the lines is not specified, but the sum of the lines and the space must equal border-width.)

groove

Looks as if it were carved in the canvas. (This is typically achieved by creating a “shadow” from two colors that are slightly lighter and darker than the specified border-color.)

ridge

Looks as if it were coming out of the canvas.

inset

Looks as if the content on the inside of the border is sunken into the canvas. Treated as ridge in the collapsing border model. [CSS2]

outset

Looks as if the content on the inside of the border is raised out of the canvas. Treated as groove in the collapsing border model. [CSS2]

Borders are drawn in front of the element’s background, but behind the element’s content (in case it overlaps).

Note: Border colors close to black or white may need different color calculations than colors in between in order to create the required “3D” effect of groove, ridge, inset, or outset.

Note: There is no control over the spacing of the dots and dashes, nor over the length of the dashes. Implementations are encouraged to choose a spacing that makes the corners symmetrical.

2.3. Line Thickness: the border-width properties

These properties specify the thickness of the border, i.e. the border width. Where

<line-width> = <length [0,∞]> | hairline | thin | medium | thick

Negative values are invalid. The thin, medium, and thick keywords are equivalent to 1px, 3px, and 5px, respectively. The hairline keyword is a UA-defined length, less than or equal to 1px and equal to an integer number of device pixels at the default page zoom, which represents a "just visible" line. (While it can be as large as 1px, on many devices it will be approximately 0.3px to 0.5px.)

The resolved value for the border-width properties is the used value.

If the border-style corresponding to a given border-width is none or hidden, then the used width is 0.

The flow-relative properties border-block-start-width, border-block-end-width, border-inline-start-width, and border-inline-end-width correspond to the physical properties border-top-width, border-bottom-width, border-left-width, and border-right-width. The mapping depends on the element’s writing-mode, direction, and text-orientation.

These two shorthand properties set the border-block-start-width & border-block-end-width and border-inline-start-width & border-inline-end-width, respectively. The first value represents the start side width, and the second value represents the end side width. If only one value is given, it applies to both the start and end sides.

border-width is a shorthand property for the four physical border-*-width properties. The four values set the top, right, bottom and left border, respectively. A missing left is the same as right, a missing bottom is the same as top, and a missing right is also the same as top. This is resolved individually for each list item.

Note: Although the initial width is medium, the initial style is none; therefore the used initial width is 0.

2.4. Border Shorthand Properties

These shorthand properties set the border-width, border-color, and border-style of one side of the borders of a box. Omitted values are set to their initial values.

The flow-relative properties border-block-start, border-block-end, border-inline-start, and border-inline-end correspond to the physical properties border-top, border-bottom, border-left, and border-right. The mapping depends on the element’s writing-mode, direction, and text-orientation.

These two shorthand properties set the border-block-start & border-block-end or border-inline-start & border-inline-end, respectively, both to the same style.

The border property is a shorthand property for setting the same border-width, border-color, and border-style for all four borders of a box. 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.

The border shorthand also resets border-image to its initial value. It is therefore recommended that authors use the border shorthand, rather than other shorthands or the individual properties, to override any border settings earlier in the cascade. This will ensure that border-image has also been reset to allow the new styles to take effect.

Note: The CSS Working Group intends for the border shorthand to reset all border properties in future levels of CSS as well. For example, if a border-characters property is introduced in the future to allow glyphs as borders, it will also be reset by the border shorthand. By using the border shorthand to reset borders, authors can be guaranteed a “blank canvas” no matter what properties are introduced in the future.

p { border: solid red }
p {
  border-top: solid red;
  border-right: solid red;
  border-bottom: solid red;
  border-left: solid red;
  border-image: none;
}

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

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

3. Corners

The padding edge (inner border) radius is the outer border radius minus the corresponding border thickness. In the case where this results in a negative value, the inner radius is zero. (In such cases the center of the border’s inner curve might not coincide with that of its outer curve.) Likewise the content edge radius is the padding edge radius minus the corresponding padding, or if that is negative, zero. The border and padding thicknesses in the curved region are thus interpolated from the adjoining sides, and when two adjoining borders are of different thicknesses the corner will show a smooth transition between the thicker and thinner borders.

All border styles (solid, dotted, inset, etc.) follow the curve of the border.

Note: If the center of a corner’s outer curve is past an opposite padding edge (in the border area of a side opposite the corner), the inner curve will not be a full quarter ellipse.

p { width: 70px; height: 70px; border: solid 30px; border-color: orange orange silver silver; border-top-right-radius: 100%; }

The margin edge, being outside the border edge, calculates its radius by adding the corresponding margin thickness to each border radius, with the corresponding outset-adjusted border radius applied.

3.1. Corner Clipping

Although border images are not affected by border-radius, other effects that clip painting or event handling to the border, padding, or content edge must clip to their respective curves. For example, backgrounds clip to the curve specified by background-clip, overflow values other than visible to the curved padding edge (when overflow on both axes is not visible), replaced element content to the curved content edge, pointer events to the curved border edge, etc.

Note: As border-radius reduces the interactive area of an element authors should make sure the remaining interactive area conforms to recommended minima for the platforms they target; in particular, conforming to recommended minimum touch target sizes may require larger widths and heights when border-radius is used.

DIV {
    background: black;
    color: white;
    border-radius: 1em;
    padding: 1em }

3.2. Color and Style Transitions

Color and style transitions must be contained within the segment of the border that intersects the smallest rectangle that contains both border radii as well as the center of the inner curve (which may be a point representing the corner of the padding edge, if the border radii are smaller than the border width).

If one of these borders is zero-width, then the other border takes up the entire transitional area. Otherwise, the center of color and style transitions between adjoining borders is a point along the curve that is a continuous monotonic function of the ratio of the border widths. However it is not defined what these transitions look like or what function maps from this ratio to a point on the curve.

3.3. Overlapping Curves

Corner curves must not overlap: When the sum of any two adjacent border radii exceeds the size of the border box, UAs must proportionally reduce the used values of all border radii until none of them overlap. The algorithm for reducing radii is as follows:

Let f = min(L_i/S_i), where i ∈ {top, right, bottom, left}, S_i is the sum of the two corresponding radii of the corners on side i, and L_top = L_bottom = the width of the box, and L_left = L_right = the height of the box. If f < 1, then all corner radii are reduced by multiplying them by f.

Note: This formula ensures that quarter circles remain quarter circles and large radii remain larger than smaller ones, but it may reduce corners that were already small enough, which may make borders of nearby elements that should look the same look different.

If the curve interferes with UI elements such as scrollbars, the UA may further reduce the used value of the affected border radii (and only the affected border radii) as much as necessary, but no more.

box-sizing: border-box;
width: 6em;
height: 2.5em;
border-radius: 0.5em 2em 0.5em 2em

box-sizing: border-box;
width: 6em;
height: 2em;
border-radius: 0.5em 2em 0.5em 2em