CSS Backgrounds and Borders Module Level 3

Abstract

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc. This draft contains the features of CSS level 3 relating to borders and backgrounds. It includes and extends the functionality of CSS level 2 [CSS21], which builds on CSS level 1 [CSS1]. The main extensions compared to level 2 are borders consisting of images, boxes with multiple backgrounds, boxes with rounded corners and boxes with shadows.

This module replaces two earlier drafts: CSS3 Backgrounds and CSS3 Border.

Status of this document

This is a public copy of the editors' draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as work in progress.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css3-background” in the subject, preferably like this: “[css3-background] …summary of comment…”

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 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 CSS WG maintains an issues list for this module. If there's a conflict between CSS Backgrounds and Borders Level 3 and CSS 2.1, please report it to the CSS Working Group. Since these specs are intended to be consistent with each other, conflicts indicate an error in one or both specs.

The following features are at-risk and may be dropped at the end of the CR period if there has not been enough interest from implementors: inner shadows for ‘box-shadow’, ‘border-break’, ‘background-break’.

Table of contents

• 1 Introduction
• 2 Values
• 3 Background properties
  • 3.1 Layering multiple background images
  • 3.2 The ‘background-color’ property
  • 3.3 The ‘background-image’ property
  • 3.4 The ‘background-repeat’ property
  • 3.5 The ‘background-attachment’ property
  • 3.6 The ‘background-position’ property
  • 3.7 The ‘background-clip’ property
  • 3.8 The ‘background-origin’ property
  • 3.9 The ‘background-size’ property
  • 3.10 The ‘background-break’ property
  • 3.11 The ‘background’ shorthand property
  • 3.12 The backgrounds of special elements
• 4 Border properties
  • 4.1 The ‘border-color’ properties
  • 4.2 The ‘border-style’ properties
  • 4.3 The ‘border-width’ properties
  • 4.4 The ‘border-radius’ properties
  • 4.5 The ‘border-break’ property
  • 4.6 The ‘border-top’, ‘border-bottom’, ‘border-right’, ‘border-left’, and ‘border’ properties
  • 4.7 The ‘box-shadow’ property
• 5 Border Images
  • 5.1 The ‘border-image-source’ property
  • 5.2 The ‘border-image-slice’ property
  • 5.3 The ‘border-image-outset’ property
  • 5.4 The ‘border-image-repeat’ property
  • 5.5 The ‘border-image’ shorthand
• 6 Definitions
  • 6.1 Glossary
  • 6.2 Conformance
  • 6.3 Levels
    • 6.3.1 CSS Level 1
    • 6.3.2 CSS Level 2
    • 6.3.3 CSS Level 3
  • 6.4 CR exit criteria
• 7 Acknowledgments
• 8 References
  • Normative references
  • Other references
• Property index
• Index

1 Introduction

This section is not normative.

When elements are rendered according to the CSS box model [CSS21], each element is either not displayed at all, or formatted as one or more rectangular boxes. Each 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 margin may actually be negative, but margins have no influence on the background and border.)

The properties of this module deal with the decoration of the border area and with the background of the content, padding and border areas. Additionally the box may be given a "drop-shadow" effect with the ‘box-shadow’ property.

If an element is broken into multiple boxes, ‘border-break’ and ‘background-break’ define how the borders and background are divided over the various boxes. (An element can result in more than one box if it is broken at the end of a line, at the end of a column or at the end of a page; and continued in the next line, column or page.)

The relative stacking order of backgrounds, borders, and shadows is given in this module. For how these layers interact with other rendered content, see Appendix E “Elaborate description of Stacking Contexts” in [CSS21].

2 Values

This specification follows the CSS property definition conventions from [CSS21].

<color> values are defined in CSS Color Level 3 [CSS3COLOR].

<image> values are defined by this specification as <image> = <uri>.

A future specification may expand the definition of <image> to allow other values, e.g. to define image slices.

All other values are defined in CSS Level 2 Revision 1 [CSS21].

All properties defined in this specification also accept the inherit keyword as their value, but for readability it has not been listed explicitly.

3 Background properties

Each box has a background layer that may be fully transparent (the default), or filled with a color and/or one or more images. The background properties specify what color (‘background-color’) and images (‘background-image’) to use, and how they are sized, positioned, tiled, etc.

The background properties are not inherited, but the parent box's background will shine through by default because of the initial ‘transparent’ value on ‘background-color’.

3.1 Layering multiple background images

The background of a box can have multiple layers in CSS3. The number of layers is determined by the number of comma-separated values in the ‘background-image’ property. Note that a value of ‘none’ still creates a layer.

Each of the images is sized, positioned, and tiled according to the corresponding value in the other background properties. The lists are matched up from the first value: excess values at the end are not used. If a property doesn't have enough comma-separated values to match the number of layers, the UA must calculate its used value by repeating the list of values until there are enough.

background-image: url(flower.png), url(ball.png), url(grass.png);
background-position: center center, 20% 80%, top left, bottom right;
background-origin: border-box, content-box;
background-repeat: no-repeat;

background-image: url(flower.png), url(ball.png), url(grass1.png);
background-position: center center, 20% 80%, top left;
background-origin: border-box, content-box, border-box;
background-repeat: no-repeat, no-repeat, no-repeat;

The first image in the list is the layer closest to the user, the next one is painted behind the first, and so on. The background color, if present, is painted below all of the other layers.

Note that the border-image properties can also define a background image, which, if present, is painted on top of the background created by the background properties.

3.2 The ‘background-color’ property

This property sets the background color of an element. The color is drawn behind any background images.

h1 { background-color: #F00 } /* Sets background to red. */

The background color is clipped according to the ‘background-clip’ value associated with the bottom-most background image.

3.3 The ‘background-image’ property

This property sets the background image(s) of an element. Images are drawn with the first specified one on top (closest to the user) and each subsequent image behind the previous one. Where

<bg-image> = <image> | none

A value of ‘none’ counts as an image layer but draws nothing. An image that is empty (zero width or zero height), that fails to download, or that cannot be displayed (e.g., because it is not in a supported image format) likewise counts as a layer but draws nothing.

See the section “Layering multiple background images” for how ‘background-image’ interacts with other comma-separated background properties to form each background image layer.

When setting a background image, authors should also specify a ‘background-color’ that will preserve contrast with the text for when the image is unavailable.

body { background-image: url("marble.svg") }
p { background-image: none }
div { background-image: url(tl.png), url(tr.png) }

Implementations may optimize by not downloading and drawing images that are not visible (e.g., because they are behind other, fully opaque images).

3.4 The ‘background-repeat’ property

Specifies how background images are tiled after they have been sized and positioned. Where

<repeat> = repeat-x | repeat-y | [repeat | space | round | no-repeat]{1,2}

Single values for <repeat> have the following meanings:

repeat-x

Equivalent to ‘repeat no-repeat’.

repeat-y

Equivalent to ‘no-repeat repeat’.

repeat

Equivalent to ‘repeat repeat’.

no-repeat

Equivalent to ‘no-repeat no-repeat’

space

Equivalent to ‘space space’

round

Equivalent to ‘round round’

If a <repeat> value has two keywords, the first one is for the horizontal direction, the second for the vertical one, as follows:

repeat

The image is repeated in this direction as often as needed to cover the background painting area.

no-repeat

The image is placed once and not repeated in this direction.

space

The image is repeated as often as will fit within the background positioning area without being clipped and then the images are spaced out to fill the area. The first and last images touch the edges of the area. If the background painting area is larger than the background positioning area, then the pattern repeats to fill the background painting area. The value of ‘background-position’ for this direction is ignored, unless there is not enough space for two copies of the image in this direction, in which case only one image is placed and ‘background-position’ determines its position in this direction.

round

The image is repeated as often as will fit within the background positioning area. If it doesn't fit a whole number of times, it is reduced in size until it does. See explanation under ‘background-size’. If the background painting area is larger than the background positioning area, then the pattern repeats to fill the background painting area.

Unless one of the two keywords is ‘no-repeat’, the whole background painting area will be tiled, i.e., not just one vertical strip and one horizontal strip.

body {
  background: white url("pendant.png");
  background-repeat: repeat-y;
  background-position: center;
}

body {
  background-image: url(dot.png) white;
  background-repeat: space
}

See the section “Layering multiple background images” for how ‘background-repeat’ interacts with other comma-separated background properties to form each background image layer.

3.5 The ‘background-attachment’ property

If background images are specified, this property specifies whether they are fixed with regard to the viewport (‘fixed’) scroll along with the element (‘scroll’ and ‘local’). Where

<attachment> = scroll | fixed | local

Note that there is only one viewport per view. If an element has a scrolling mechanism (see the ‘overflow’ property [CSS21]), a ‘fixed’ background doesn't move with the element, and a ‘scroll’ background doesn't move with the scrolling mechanism.

The difference between ‘scroll’ and ‘local’ is only visible when the element has a scrolling mechanism: in the case of ‘scroll’, the background does not scroll with the element's content. (It is attached to the element's border, effectively.) In the case of ‘local’, the background scrolls along with the element's content. In this case, the background behind the element's border (if any) scrolls as well, even though the border itself does not scroll with the contents. The UA may, however, treat the ‘border-box’ value of ‘background-clip’ as ‘padding-box’ in cases where ‘background-attachment’ is ‘local’ and the contents of the element scroll.

In paged media where there is no viewport, a ‘fixed’ background is fixed with respect to the page box.

Even if the image is fixed, it is still only visible when it is in the background painting area of the element or otherwise unclipped. Thus, unless the image is tiled, it may be invisible.

body {
  background: red url("pendant.gif");
  background-repeat: repeat-y;
  background-attachment: fixed;
}

User agents that do not support ‘fixed’ backgrounds (for example due to limitations of the hardware platform) should ignore declarations with the keyword ‘fixed’. For example:

body {
   /* For all UAs: */
   background: white url(paper.png) scroll;
   /* For UAs that do fixed backgrounds: */
   background: white url(ledger.png) fixed;
}
h1 {
   /* For all UAs: */
   background: silver;
   /* For UAs that do fixed backgrounds: */
   background: url(stripe.png) fixed, white url(ledger.png) fixed;
}

See the section “Layering multiple background images” for how ‘background-attachment’ interacts with other comma-separated background properties to form each background image layer.

3.6 The ‘background-position’ property

If background images have been specified, this property specifies their initial position (after any resizing) within their corresponding background positioning area.

Where

<bg-position> = [
  [ [ <percentage> | <length> | left | center | right ] ]
  [ [ <percentage> | <length> | top | center | bottom ] ]?
|
  [ center | [ left | right ] [ <percentage> | <length> ]? ] ||
  [ center | [ top | bottom ] [ <percentage> | <length> ]? ]
]

If only one value is specified, the second value is assumed to be ‘center’. If two values are given and at least one value is not a keyword, then the first value represents the horizontal position (or offset) and the second represents the vertical position (or offset). <percentage> and <length> values here represent an offset of the top left corner of the background image from the top left corner of the background positioning area.

If three or four values are given, then each <percentage> or <length> represents an offset and must be preceded by a keyword, which specifies from which edge the offset is given. For example, ‘background-position: bottom 10px right 20px’ represents a ‘10px’ vertical offset up from the bottom edge and a ‘20px’ horizontal offset leftward from the right edge. If three values are given, the missing offset is assumed to be zero.

Positive values represent an offset inward from the edge of the background positioning area. Negative values represent an offset outward from the edge of the background positioning area.

   background-position: left 10px top 15px;   /* 10px, 15px */
   background-position: left      top     ;   /*  0px,  0px */
   background-position:      10px     15px;   /* 10px, 15px */
   background-position: left          15px;   /*  0px, 15px */
   background-position:      10px top     ;   /* 10px,  0px */
   background-position: left      top 15px;   /*  0px, 15px */
   background-position: left 10px top     ;   /* 10px,  0px */

<percentage>

A percentage for the horizontal offset is relative to (width background positioning area - width of background image). A percentage for the vertical offset is relative to (height background positioning area - height of background image), where the size of the image is the size given by ‘background-size’.

For example, with a value pair of ‘0% 0%’, the upper left corner of the image is aligned with the upper left corner of, usually, the box's padding edge. A value pair of ‘100% 100%’ places the lower right corner of the image in the lower right corner of the area. With a value pair of ‘75% 50%’, the point 75% across and 50% down the image is to be placed at the point 75% across and 50% down the area.

Diagram of the meaning of ‘background-position: 75% 50%’.

<length>

A length value gives a fixed length as the offset. For example, with a value pair of ‘2cm 1cm’, the upper left corner of the image is placed 2cm to the right and 1cm below the upper left corner of the background positioning area.

top

Equivalent to ‘0%’ for the vertical position if one or two values are given, otherwise specifies the top edge as the origin for the next offset.

right

Equivalent to ‘100%’ for the horizontal position if one or two values are given, otherwise specifies the right edge as the origin for the next offset.

bottom

Equivalent to ‘100%’ for the vertical position if one or two values are given, otherwise specifies the bottom edge as the origin for the next offset.

left

Equivalent to ‘0%’ for the horizontal position if one or two values are given, otherwise specifies the left edge as the origin for the next offset.

center

Equivalent to ‘50%’ (‘left 50%’) for the horizontal position if it is not otherwise given, or ‘50%’ (‘top 50%’) for the vertical position if it is.

  body { background: url("banner.jpeg") right top }    /* 100%   0% */
  body { background: url("banner.jpeg") top center }   /*  50%   0% */
  body { background: url("banner.jpeg") center }       /*  50%  50% */
  body { background: url("banner.jpeg") bottom }       /*  50% 100% */
  

  body {
    background-image: url("logo.png");
    background-attachment: fixed;
    background-position: 100% 100%;
    background-repeat: no-repeat;
  }
  

background-position: right 3em bottom 10px

See the section “Layering multiple background images” for how ‘background-position’ interacts with other comma-separated background properties to form each background image layer.

3.7 The ‘background-clip’ property

Determines the background painting area. Values have the following meanings:

padding-box

The background is painted within (clipped to) the padding box.

border-box

The background is painted within (clipped to) the border box.

Note that the background is always drawn behind the border, if any. See “Elaborate description of Stacking Contexts” in [CSS21].

See the section “Layering multiple background images” for how ‘background-clip’ interacts with other comma-separated background properties to form each background image layer.

3.8 The ‘background-origin’ property

For elements rendered as a single box, specifies the background positioning area. For elements rendered as multiple boxes (e.g., inline boxes on several lines, boxes on several pages) specifies which boxes the ‘background-break’ operates on to determine the background positioning area(s). Where

<bg-origin> = border-box | padding-box | content-box

padding-box

The position is relative to the padding box. (For single boxes ‘0 0’ is the upper left corner of the padding edge, ‘100% 100%’ is the lower right corner.)

border-box

The position is relative to the border box.

content-box

The position is relative to the content box.

If the ‘background-attachment’ value for this image is ‘fixed’, then this property has no effect: in this case the background positioning area is the initial containing block [CSS21].

Note that if ‘background-clip’ is ‘padding-box’, ‘background-origin’ is ‘border-box’, and ‘background-position’ is top left (the initial value), then the top left of the background image will be clipped.

See the section “Layering multiple background images” for how ‘background-clip’ interacts with other comma-separated background properties to form each background image layer.

3.9 The ‘background-size’ property

Specifies the size of the background images. Where

<bg-size> = [ <length> | <percentage> | auto ]{1,2} | cover | contain

Values have the following meanings:

contain

Scale the image, while preserving its intrinsic aspect ratio (if any), to the largest size such that both its width and its height can fit inside the background positioning area.

cover

Scale the image, while preserving its intrinsic aspect ratio (if any), to the largest size such that both its width and its height can completely cover the background positioning area.

[ <length> | <percentage> | auto ]{1,2}

The first value gives the width of the corresponding image, the second value its height. If only one value is given the second is assumed to be ‘auto’.

A percentage is relative to the background positioning area.

An ‘auto’ value for one dimension is resolved by using the image's intrinsic ratio and the size of the other dimension, or failing that, using the image's intrinsic size, or failing that, treating it as 100%.

If both values are ‘auto’ then the intrinsic width and/or height of the image should be used, if any, the missing dimension (if any) behaving as ‘auto’ as described above. If the image has neither an intrinsic width nor an intrinsic height, its size is determined as for ‘contain’.

Negative values are not allowed.

div {
    background-image: url(plasma.png);
    background-size: 100% 100%;
    background-origin: content-box }

p {
    background-image: url(tubes.png);
    background-size: 50% auto;
    background-origin: border-box }

para {
    background-size: 15px 15px;
    background-image: url(tile.png)}

body {
    background-size: auto;            /* default */
    background-image: url(flower.png) }

p {
    background-image: url(chain.png);
    background-repeat: no-repeat round;
    background-size: 20% 30% }

If ‘background-repeat’ is ‘round’ for one (or both) directions, there is a second step. The UA must reduce the size in that direction (or both directions) so that the image fits a whole number of times in the background area. In the case of the width:

If X ≠ 0 is the width of the image after step one and W is the width of the background area, then the rounded width X' = W / ceil(W / X)

The height is analogous. ceil() is a function that returns its argument if it is a whole number, otherwise the next bigger whole number.

If ‘background-repeat’ is ‘round’ for one direction only and if ‘background-size’ is ‘auto’ for the other direction, then there is a third step: that other direction is scaled so that the original aspect ratio is restored.

div {
  background-image: url(image1.png);
  background-repeat: repeat;         /* default */
  background-size: auto }            /* default */

div {
  background-image: url(image2.png);
  background-repeat: repeat;         /* default */
  background-size: 3em }             /* = '3em auto' */

div {
  background-image: url(image3.png);
  background-repeat: round repeat;
  background-size: 3em auto }

div {
  background-image: url(image4.png);
  background-repeat: repeat round;
  background-size: 3em auto }

div {
  background-image: url(image5.png);
  background-repeat: round;
  background-size: auto 4em }

If the background image's width or height resolves to zero, this causes the image not to be displayed. (The effect is the same as if it had been a transparent image.)

See the section “Layering multiple background images” for how ‘background-clip’ interacts with other comma-separated background properties to form each background image layer.

3.10 The ‘background-break’ property

This property applies to elements when they are broken into several boxes (for example, across lines or across pages). It specifies how the background positioning area is derived from these multiple boxes and how the element's background is drawn within them.

Values have the following meanings:

bounding-box

The background positioning area is the smallest rectangle that encloses all broken boxes of the element. If the boxes are on different pages, the pages are treated as one continuous page—as if their page content areas were glued together in the block progression direction of the root element (i.e. glued together top to bottom for horizontal text mode)—and the rectangle drawn on this continuous page. If the page content areas have different widths, then they are aligned on the start edge (as defined by the properties applied to the root element). The background is only painted where indicated by ‘background-clip’.

each-box

The background is drawn independently in each box of the element. A no-repeat background image will thus be rendered once in each box of the element.

continuous

The effect is as if, after the element has been laid out (including any justification, bidi reordering, page breaks, etc.), all the element's boxes are taken and put one after the other in visual order. The background is applied to the bounding box of this composite box and then the boxes are put back, with their share of the background.

For boxes broken across lines, first boxes on the same line are connected in visual order. Then boxes on subsequent lines are ordered according to the element's inline progression direction and aligned on the baseline. For example in a left-to-right containing block (‘direction’ is ‘ltr’), the first box is the leftmost box on the first line and boxes from subsequent lines are put to the right of it. In a right-to-left containing block, the first box is the rightmost on the first line and subsequent boxes are put to the left of it.

For boxes broken across columns, the the columns are treated as one continuous element, as if the column boxes were glued together in the block progression direction of the multi-column element. For boxes broken across pages, the page content areas are glued together in the block progression direction of the root element. In these cases, if the pieces have different widths (heights, if the root element / multi-column element is in vertical text mode), then each piece draws its background assuming that the whole element has the same width (height) as this piece. This ensures that right-aligned images stay aligned to the right edge, left-aligned images stay aligned to the left edge, and centered images stay centered.

3.11 The ‘background’ shorthand property

Where

<bg-layer> = <bg-image> || <bg-position> || / <bg-size> || <repeat> || <attachment> || <bg-origin> 

where ‘<bg-position>’ must not occur before ‘/ <bg-size>’ if both are present.

<final-bg-layer> = <bg-image> || <bg-position> || / <bg-size> || <repeat> || <attachment> || <bg-origin> || <'background-color'>

where ‘<bg-position>’ must not occur before ‘/ <bg-size>’ if both are present.

Note that a color is permitted in <final-bg-layer>, but not in <bg-layer>.

The ‘background’ property is a shorthand property for setting most background properties at the same place in the style sheet. Given a valid declaration, the shorthand first sets each of ‘background-color’, ‘background-position’, ‘background-size’, ‘background-repeat’, ‘background-origin’, ‘background-clip’, ‘background-attachment’ and ‘background-image’ to its initial value, then assigns explicit values given in the declaration.

If ‘background-origin’ is present and its value matches a possible value for ‘background-clip’ then it also sets ‘background-clip’ to that value. For example, ‘background: border-box’ sets both ‘background-origin’ and ‘background-clip’ to ‘border-box’.

The ‘background’ shorthand does not set ‘background-break’.

body { background: red }
p { background: url("chess.png") / 10em gray
       40% round fixed border border}

body {
    background-color: red;
    background-position: 0% 0%;
    background-size: auto auto;
    background-repeat: repeat repeat;
    background-clip: border-box;
    background-origin: padding-box;
    background-attachment: scroll;
    background-image: none }

p {
    background-color: gray;
    background-position: 40% 50%;
    background-size: 10em 10em;
    background-repeat: round round;
    background-clip: border-box;
    background-origin: border-box;
    background-attachment: fixed;
    background-image: url(chess.png) }

E { background: #CCC url("metal.jpg") /100% auto no-repeat top left }

div { background: padding url(paper.jpg) white center }
div {
    background-color: white;
    background-image: url(paper.jpg);
    background-repeat: repeat;
    background-attachment: scroll;
    background-position: center;
    background-clip: padding-box;
    background-origin: padding-box;
    background-size: auto auto }

background: url(a.png) top left no-repeat,
            url(b.png) center / 100% 100% no-repeat,
            url(c.png) white;

background-image:      url(a.png),  url(b.png),        url(c.png);
background-position:   top left,    center,            top left;
background-repeat:     no-repeat,   stretch no-repeat, repeat;
background-clip:       border-box,  border-box,        border-box;
background-origin:     padding-box, padding-box,       padding-box;
background-size:       auto auto,   100% 100%,         auto auto;
background-attachment: scroll,      scroll,            scroll;
background-color:      white;

Note that ‘background: url(foo) white’ and ‘background: url(foo), white’ have the same effect.

3.12 The backgrounds of special elements

The background of the root element becomes the background of the canvas and its background painting area extends to cover the entire canvas, although any images are sized and positioned relative to the root element as if they were painted for that element alone. (In other words, the background positioning area is determined as for the root element.) If the root's ‘background-color’ value is ‘transparent’, the canvas's background color is UA dependent. The root element does not paint this background again, i.e. the used value of its background is transparent.

For documents whose root element is an HTML HTML element or an XHTML html element: if the computed value of ‘background-image’ on the root element is ‘none’ and its ‘background-color’ is ‘transparent’, user agents must instead propagate the computed values of the background properties from that element's first HTML BODY or body child element. The used values of that BODY element's background properties are their initial values, and the propagated values are treated as if they were specified on the root element. It is recommended that authors of HTML documents specify the canvas background for the BODY element rather than the HTML element.

<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.0//EN'
  >
<html>
  <head>
    <title>Setting the canvas background</title>
    <style type="text/css">
       body { background: url("http://example.org/marble.png") }
    </style>
  </head>
  <body>
    <p>My background is marble.</p>
  </body>
</html>

The ‘::first-line’ pseudo-element is like an inline-level element for the purposes of the background (see section 5.12.1 of [CSS21]). That means, e.g., that in a left-justified first line, the background does not necessarily extend all the way to the right margin.

4 Border properties

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.

4.1 The ‘border-color’ properties

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

‘Border-color’ is a shorthand for the four ‘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.

4.2 The ‘border-style’ properties

These properties set the style of the border, unless there is a border image

‘Border-style’ is a shorthand for the other four. Its 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.

Where

<border-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, unless the border is an image, see ‘background-image’

hidden

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

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 ‘border-color’.)

ridge

Looks as if it were coming out of the canvas.

inset

Looks as if the content on inside of the border is sunken into the canvas. Treated as ‘ridge’ in border-collapsed tables. [CSS21]

outset

Looks as if the content on the inside of the border is coming out of the canvas. Treated as ‘groove’ in border-collapsed tables. [CSS21]

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

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.

Note: This specification does not define how borders of different styles should be joined in the corner. Also note that rounded corners may cause the corners and the contents to overlap, if the padding is less than the radius of the corner.

4.3 The ‘border-width’ properties

These properties set the thickness of the border. Where

<border-width> = <length> | thin | medium | thick

The <length> may not be negative. The lengths corresponding to ‘thin’, ‘medium’ and ‘thick’ are not specified, but the values are constant throughout a document and thin ≤ medium ≤ thick. A UA could, e.g., make the thickness depend on the ‘medium’ font size: one choice might be 1, 3 & 5px when the ‘medium’ font size is 17px or less.

‘Border-width’ is a shorthand that sets the four ‘border-*-width’ properties. If it has four values, they set top, right, bottom and left in that order. If left is missing, it is the same as right; if bottom is missing, it is the same as top; if right is missing, it is the same as top.

Note that the initial width is ‘medium’, but the initial style is ‘none’ and therefore the used width is 0.

When the used width of the border is 0, we say that the border is absent.

4.4 The ‘border-radius’ properties

The two length values of the ‘border-*-radius’ properties define the radii of a quarter ellipse that defines the shape of the corner of the outer border edge (see the diagram below). The first value is the horizontal radius. If the second length is omitted it is equal to the first (and the corner is thus a quarter circle). If either length is zero, the corner is square, not rounded.

The ‘border-radius’ shorthand sets all four ‘border-*-radius’ properties. If values are given before and after the slash, then the values before the slash set the horizontal radius and the values after the slash set the vertical radius. If there is no slash, then the values set both radii equally. The four values for each radii are given in the order top-left, top-right, bottom-right, bottom-left. If bottom-left is omitted it is the same as top-right. If bottom-right is omitted it is the same as top-left. If top-right is omitted it is the same as top-left.

border-radius: 4em;

border-top-left-radius:     4em;
border-top-right-radius:    4em;
border-bottom-right-radius: 4em;
border-bottom-left-radius:  4em;

border-radius: 2em 1em 4em / 0.5em 3em;

border-top-left-radius:     2em 0.5em;
border-top-right-radius:    1em 3em;
border-bottom-right-radius: 4em 0.5em;
border-bottom-left-radius:  1em 3em;

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 its center might not coincide with that of the outer border curve.) Likewise the content edge radius is the padding edge radius minus the corresponding padding, or if that is negative, zero. Thus when two adjoining borders are of different thicknesses the corner will show a smooth transition between the thicker and thinner borders.

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

Backgrounds, but not the border-image, are clipped to the appropriate curve (as determined by ‘background-clip’). Other effects that clip to the border or padding edge (such as ‘overflow’ other than ‘visible’) also must clip to the curve. The content of replaced elements is always trimmed to the border edge curve.

The center of color and style transitions between adjoining borders is at the point on the curve that is at an angle that is proportional to the ratio of the border widths. For example, if the two widths are equal, that point is at a 45° angle, and if one is twice the width of the other the point is at a 30° angle. The line demarcating this transition is drawn between the point at that angle on the outer curve and the point at that angle on the inner curve. The transition must be contained within the segment of the border where the tangent of the inner curve either not defined or is not parallel with the sides of the box. It is not defined what the transition looks like, but a gradient is recommended for color transitions that don't involve dotted or dashed borders.

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

Corners do not overlap: When the sum of two adjacent corner radii exceeds the size of the border box, UAs must reduce one or more of the radii. The algorithm for reducing radii is as follows:

The sum of two adjacent radii may not be more than the width or height (whichever is relevant) of the box. If any sum exceeds that value, the used values of all radii are reduced according to the following formula: Let f = min(L_i/S_i), where i ∈ {top, right, bottom, left}, S_i is the sum of the 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 that 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.

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

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

The UA may apply the border-radius properties to ‘table’ and ‘inline-table’ elements when ‘border-collapse’ is ‘collapse’ but is not required to. In this case not only must the border radii of adjacent corners not intersect, but the horizontal and vertical radii of a single corner may not extend past the boundaries of the cell at that corner (i.e. the cell's other corners must not be affected by this corner's border-radius). If the computed values of the border radii would cause this effect, then the used values of all the border radii of the table must be reduced by the same factor so that the radii neither intersect nor extend past the boundaries of their respective corner cells.

The CSS3 UAs should ignore border-radius properties applied to internal table elements when ‘border-collapse’ is ‘collapse’. The effect of border-radius on internal table elements is undefined in CSS3 Backgrounds and Borders, but may be defined in a future specification.

DIV.standout {
    width: 13em;
    height: 8em;
    border: solid black 1em;
    border-radius: 7.5em 5em }

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

4.5 The ‘border-break’ property

When a box that has a border is broken at a page break, column break, or, for inline elements, at a line break, a border and some padding can be inserted at the break, or the border can be left open.

If the value of ‘border-break’ is ‘close’, then each box is independently wrapped with the border and padding. The ‘border-radius’, ‘border-image’, and ‘box-shadow’, if any, are applied to each box independently.

Otherwise, if the style is set to ‘none’, no border and no padding are inserted at the break. If some other border style is given, padding is added as wide as the corresponding side of the ‘padding’ property, and a border is added with the specified style, width, and color. In either case, no box-shadow is drawn at the broken edge; ‘border-radius’ has no effect at its corners; and the ‘border-image’ is rendered for the whole box as if it were unbroken. The effect is as though the element were rendered with no break present, and then sliced by the break afterward.

Note this means that padding is added if the border style is ‘hidden’, but not if the border style is ‘none’.

For inline elements side of the box that breaks is determined by the element's inline progression direction, not that of the containing block. For example, the first part of an inline element with ‘direction: rtl’ inside a block with ‘direction: ltr’ will break on the left side.

4.6 The ‘border-top’, ‘border-bottom’, ‘border-right’, ‘border-left’, and ‘border’ properties

This is a shorthand property for setting the width, style, and color of the top, right, bottom, and left border of a box. Omitted values are set to their initial values.

The ‘border’ property is a shorthand property for setting the same width, color, and 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.

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
}

4.7 The ‘box-shadow’ property

The ‘box-shadow’ property attaches one or more drop-shadows to the box. The property is a comma-separated list of shadows, each specified by 2-4 length values, an optional color, and an optional ‘inset’ keyword. Omitted lengths are 0, omitted colors are a UA-chosen color.

Where

<shadow> = inset? && [ <length>{2,4} && <color>? ]

The components of each <shadow> are interpreted as follows:

• The first length is the horizontal offset of the shadow. A positive value draws a shadow that is offset to the right of the box, a negative length to the left.
• The second length is the vertical offset. A positive value offsets the shadow down, a negative one up.
• The third length is a blur radius. Negative values are not allowed. If it is 0, the shadow is sharp, otherwise the larger the value, the more the shadow is blurred. The exact algorithm is not specified.
• The fourth length is a spread radius. Positive values cause the shadow to grow in all directions by the specified radius. Negative values cause the shadow to shrink. The shadow should not change shape when a spread radius is applied: sharp corners should remain sharp.
• The color is the color of the shadow.
• The ‘inset’ keyword, if present, changes the drop shadow from an outer shadow (one that shadows the box onto the canvas, as if it were lifted above the canvas) to an inner shadow (one that shadows the canvas onto the box, as if the box were cut out of the canvas and shifted behind it).

An outer box-shadow casts a shadow as if the border-box of the element were opaque. The shadow is drawn outside the border edge only: it is not drawn inside the border-box of the element.

An inner box-shadow casts a shadow as if everything outside the padding edge were opaque. The inner shadow is drawn inside the padding edge only: it is not drawn outside the padding box of the element.

If the box has a nonzero ‘border-radius’, the shadow is rounded in the same way. If an element has multiple boxes, all of them get drop shadows, but shadows are only drawn where borders would also be drawn, see ‘border-break’.

The shadow effects are applied front-to-back: the first shadow is on top and the others are layered behind. Shadows do not influence layout and may overlap other boxes or their shadows. In terms of stacking contexts and the painting order, the outer shadows of an element are drawn immediately below the background of that element, and the inner shadows of an element are drawn immediately above the background of that element (below the borders and border image, if any).

Below are some examples of an orange box with a blue border being being given a drop shadow.

border:5px solid blue; background-color:orange; width: 144px; height: 144px;	border-radius: 20px;	border-radius: 0;
box-shadow: rgba(0,0,0,0.4) 10px 10px;
box-shadow: rgba(0,0,0,0.4) 10px 10px inset
box-shadow: rgba(0,0,0,0.4) 10px 10px 0 10px /* spread */
box-shadow: rgba(0,0,0,0.4) 10px 10px 0 10px /* spread */ inset

The ‘box-shadow’ property applies to the ‘::first-letter’ pseudo-element, but not the ‘::first-line’ pseudo-element. Outer shadows have no effect on internal table elements in the collapsing border model. If a shadow is defined for single border edge in the collapsing border model has multiple border thicknesses (e.g. an outer shadow on a table where one row has thicker borders than the others, or an inner shadow on a rowspanning table cell that adjoins cells with different border thicknesses), the exact position and rendering its shadows are undefined.

5 Border Images

Authors can specify an image to be used in place of the border styles. In this case, the border's design is taken from the sides and corners of an image specified with ‘border-image-source’, whose pieces may be sliced, scaled and stretched in various ways to fit the size of the border area.

5.1 The ‘border-image-source’ property

Specifies an image to use instead of the border styles given by the ‘border-style’ properties and as an additional background layer for the element. If the value is ‘none’ or if the image cannot be displayed, the border styles will be used.

5.2 The ‘border-image-slice’ property

The four ‘border-image-slice’ values represent inward offsets from the top, right, bottom, and left edges of the image (respectively), dividing it into nine regions: four corners, four edges and a middle. The middle image part is discarded (treated as fully transparent) unless the ‘fill’ keyword is present.

If the fourth number/percentage is absent, it is the same as the second. If the third one is also absent, it is the same as the first. If the second one is also absent, it is the same as the first.

Percentages are relative to the size of the image. Numbers represent pixels in the image (if the image is a raster image) or vector coordinates (if the image is a vector image). Negative values are not allowed and values bigger than the size of the image are interpreted as 100%.

The regions given by the ‘border-image-slice’ values may overlap. However if the sum of the right and left widths is equal to or greater than the width of the image, the images for the top and bottom edge and the middle part are empty, which has the same effect as if a nonempty transparent image had been specified for those parts. Analogously for the top and bottom values.

The border image is drawn inside an area called the border image area. This is a nine-part area whose boundaries by default correspond to the border box.

The four numeric, percentage, or length values of ‘border-image-width’ specify offsets that are used to divide the border-image area into nine parts. The four values represent inward distances from the the top, right, bottom, and left sides of the border-image area, respectively. If the fourth value is absent, it is the same as the second. If the third one is also absent, it is the same as the first. If the second one is also absent, it is the same as the first. Percentages refer to the size of the border-image area. Numbers represent multiples of the corresponding border-width.

Should percentages be used instead of numbers for ratios?

If ‘intrinsic’ is specified then the border image widths are found from the intrinsic sizes of the image slices. If the image does not have the required intrinsic dimensions then the corresponding border-width is used instead.

If two opposite ‘border-image-width’ offsets are large enough that they overlap, then their used values are proportionally reduced until they no longer overlap.

5.3 The ‘border-image-outset’ property

The border-image-outset values specify the amount by which the border image area extends beyond the border box on the top, right, bottom, and left sides respectively. If the fourth length is absent, it is the same as the second. If the third one is also absent, it is the same as the first. If the second one is also absent, it is the same as the first. Numbers represent multiples of the corresponding border-width.

Negative values are not allowed for any of the border-image values.

5.4 The ‘border-image-repeat’ property

This property specifies how the images for the sides and the middle part of the border image are scaled and tiled. If the second keyword is absent, it is assumed to be the same as the first.

The WG wanted to solicit ideas for an alternative name to this property.

The nine images are scaled and tiled in four steps:

step 1

• The two images for the top and bottom edges are made as tall as the top and bottom border-image area parts, respectively, and their width is scaled proportionally.

• The images for the left and right edge are made as wide as the left and right border-image area parts, respectively, and their height is scaled proportionally.

• The corner images are scaled to be as wide and as tall as the two border-image edges they are part of.

• The middle image's width is scaled by the same factor as the top image unless that factor is zero or infinity, in which case the scaling factor of the bottom is substituted, and failing that, the width is not scaled. The height of the middle image is scaled by the same factor as the left image unless that factor is zero or infinity, in which case the scaling factor of the right image is substituted, and failing that, the height is not scaled.

step 2

• If the first keyword is ‘stretch’, the top, middle and bottom images are further scaled to be as wide as the middle part of the border-image area. The height is not changed any further.

• If the first keyword is ‘round’, the top, middle and bottom images are reduced in width, so that exactly a whole number of them fit in the middle part of the border-image area, as follows:

  If X ≠ 0 is the width of the image and W is the width of the padding area, then the rounded width X' = W / ceil(W / X)

• If the first keyword is ‘repeat’, the top, middle, and bottom images are not changed any further.

• The effects of ‘stretch’, ‘round’, and ‘repeat’ for the second keyword are analogous, acting on the height of the left, middle and right images.

step 3

• If the first keyword is ‘round’, the top, middle, and bottom images are placed at the left edge of their respective parts of the border-image area. Otherwise the images are centered horizontally in their respective areas.

• If the second keyword is ‘round’, the left, middle, and right images are placed at the top edge of their respective parts of the border-image area. Otherwise the images are centered vertically in their respective areas.

step 4

• The images are then tiled within their respective areas. All images are drawn at the same stacking level as normal borders: immediately in front of the background layers.

DIV {
  border-image: url("border.png") 27 round stretch;
  border: double orange 1em }

5.5 The ‘border-image’ shorthand

This is a shorthand property for setting ‘border-image-source’, ‘border-image-slice’, ‘border-image-width’, ‘border-image-outset’ and ‘border-image-repeat’. Omitted values are set to their initial values.

6 Definitions

6.1 Glossary

The following terms and abbreviations are used in this module.

UA

User Agent

A program that reads and/or writes CSS style sheets on behalf of a user in either or both of these categories: programs whose purpose is to render documents (e.g., browsers) and programs whose purpose is to create style sheets (e.g., editors). A UA may fall into both categories. (There are other programs that read or write style sheets, but this module gives no rules for them.)

document

A tree-structured document with elements and attributes, such as an SGML or XML document [XML11].

style sheet

A CSS style sheet.

6.2 Conformance

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:

Informative notes begin with the word "Note" and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformance to CSS Backgrounds and Borders Level 3 is defined for three 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 CSS Backgrounds and Borders Level 3 if all of its declarations that use properties defined in this module have values that are valid according to the generic CSS grammar and the individual grammars of each property as given in this module.

A renderer is conformant to CSS Backgrounds and Borders Level 3 if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the properties defined by CSS Backgrounds and Borders Level 3 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 CSS Backgrounds and Borders Level 3 if it writes syntactically correct style sheets, according to the generic CSS grammar and the individual grammars of each property in this module.

6.3 Levels

This section is informative. CSS has different levels of features, each a subset of the other. (See [CSSBEIJING] for a full explanation.) The lists below describe which features from this specification are in each level.

6.3.1 CSS Level 1

• ‘background-color’
• ‘background-image’ only one image (no layers)
• ‘background-repeat’: only ‘repeat’ | ‘repeat-x’ | ‘repeat-y’ | ‘no-repeat’
• ‘background-attachment’: only ‘scroll’ | ‘fixed’
• ‘background-position’: only one or two values allowed
• ‘background’ shorthand: only color, image, repeat, attachment and position
• ‘border-color’ properties
• ‘border-style’ properties
• ‘border-width’ properties
• ‘border-top’, ‘border-bottom’, ‘border-right’, ‘border-left’, and ‘border’ shorthands

6.3.2 CSS Level 2

• ‘background-color’
• ‘background-image’: only one image (no layers)
• ‘background-repeat’: only ‘repeat’ | ‘repeat-x’ | ‘repeat-y’ | ‘no-repeat’
• ‘background-attachment’: only ‘scroll’ | ‘fixed’
• ‘background-position’: only one or two values allowed
• ‘background’: only color, image, repeat, attachment and position
• ‘border-color’ properties
• ‘border-style’ properties
• ‘border-width’ properties
• ‘border-top’, ‘border-bottom’, ‘border-right’, ‘border-left’, and ‘border’ shorthands

6.3.3 CSS Level 3

• All features described in the CSS Backgrounds and Borders Module Level 3

6.4 CR exit criteria

As described in the W3C process document, a Candidate Recommendation (CR) is a specification that W3C recommends for use on the Web. The next stage is “Recommendation,” when the specification is sufficiently implemented.

For this specification to be proposed as a W3C Recommendation, the following conditions shall be met. 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