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.

Not all the corrections and clarifications in the revised edition of CSS2 [CSS21] have been applied to this draft yet. In case of conflict (other than on properties and values that are clearly new to CSS3), CSS 2.1 probably represents the intention of the CSS WG better than this draft.

The CSS WG maintains an issues list for this module.

Table of contents

• 1. Dependencies with other CSS 3 Modules
• 2. Context
  • 2.1 Modularization of CSS
  • 2.2 Changes from CSS 2.1
• 3. The layout model of backgrounds and borders
• 4. Background properties
  • 4.1 The ‘background-color’ property
  • 4.2 The ‘background-image’ property
  • 4.3 The ‘background-repeat’ property
  • 4.4 The ‘background-attachment’ property
  • 4.5 The ‘background-position’ property
  • 4.6 The ‘background-clip’ property
  • 4.7 The ‘background-origin’ property
  • 4.8 The ‘background-size’ property
  • 4.9 The ‘background-break’ property
  • 4.10 Layering multiple background images
  • 4.11 The ‘background’ property
  • 4.12 The background of the canvas
• 5. Border properties
  • 5.1 The ‘border-color’ properties
  • 5.2 The ‘border-style’ properties
  • 5.3 The ‘border-width’ properties
  • 5.4 The ‘border-image’ property
  • 5.5 The ‘border-radius’ properties
  • 5.6 The ‘border-break’ property
  • 5.7 The ‘border-top’, ‘border-bottom’, ‘border-right’, ‘border-left’, and ‘border’ properties
  • 5.8 The ‘box-shadow’ property
• 6. Definitions
  • 6.1 Profiles
  • 6.2 Conformance
  • 6.3 Glossary
  • 6.4 CR exit criteria
• 7. Acknowledgments
• 8. References
  • Normative references
  • Other references
• Property index
• Index

1. Dependencies with other CSS 3 Modules

This module depends on:

• CSS Values and Units [CSS3VAL]: the types <length>, <non-negative-number>, <percentage> and <uri>.
• CSS Box Model [CSS3BOX]: the properties ‘margin’ and ‘overflow’; the definition of border box, padding box and content box.
• CSS 2.1 [CSS21] (in particular the box model of section 8.1)
• CSS Color Module [CSS3COLOR]: the <color> type and ‘color’ property.

This module refers non-normatively to the following properties:

• CSS Table Module [CSS3TBL]: the ‘border-collapse’ property.
• CSS Text Layout Module [CSS3TEXT]: the ‘direction’ property.

2. Context

2.1 Modularization of CSS

The members of the Cascading Style Sheets (CSS) Working Group proposed during the Clamart meeting to modularize the CSS specification.

This modularization, and the externalization of the general syntax, of CSS reduces the size of the specification and allows new types of specifications to use selectors and/or CSS general syntax.

This module will have its own test suite (on the CSS test suites page) with several tests per concept introduced in this document, as well as tests for multiple concepts used together. This test suite will not consist of full conformance tests, but is intended to ensure interoperability between implementations and forms part of the CR exit criteria.

See the section on Conformance for the role of modules in the implementation requirements for UAs.

2.2 Changes from CSS 2.1

[This section needs to be revised.]

‘Background-clip’, ‘background-break’, and ‘background-origin’ are new. Also there are changes to the ‘background’ shorthand property.

‘Background-attachment’ has a new value ‘local’.

The background can now have multiple images. As a consequence, several properties now accept a comma-separated list of values.

‘Box-shadow’, ‘border-image’, ‘border-break’ and ‘border-radius’ are new.

3. The layout model of backgrounds and borders

(This section is not normative.)

When elements are rendered according to the CSS box model [CSS3BOX], 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 child elements of an element usually create boxes of their own, that are placed inside the content area of their parent, although they may also be placed outside it.

The reason an element may result in more than one box, is that elements may be broken at the end of a line (for inline elements), at the end of a column or at the end of a page and create further boxes in the next line, column or page.

The properties of this module deal with the contents of the border area and with the background of the content, padding and border areas.

That background may be fully transparent (the default), or it may be filled with a color, one or more images, or both images and color. The background properties specify what color ( ‘background-color’) and images ( ‘background-image’) to use, where they are placed ( ‘background-position’), whether they are repeated or scaled ( ‘background-repeat’, ‘background-size’), etc.

The ‘border-image’ property can also define a background image, which, if present, is added on top of that of the background 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, three properties define the style of the four border sides ( ‘border-style’), color ( ‘border-color’) and thickness ( ‘border-width’). In the latter case, the sides and corners are taken from the sides and corners of an image specified with ‘border-image’. The image can be sliced, scaled and stretched in various ways to fit the size of the border.

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.

There is also another kind of decoration that can be added to an element: a drop shadow, via the ‘box-shadow’ property.

4. Background properties

4.1 The ‘background-color’ property

This property sets the background color of an element. Valid color values are defined in the Color Module [CSS3COLOR].

Note that the color is drawn behind any background images, see ‘background-image’.

The color after the slash, if present, is used instead of the first in the case the element's bottom-most background image, if any, cannot be drawn. This color is called the fallback color. If the color before the slash is missing, it is assumed to be ‘transparent’.

h1 { background-color: #F00 }
div { background-color: / white; } /* Equivalent to background-color: transparent / white; */

Both the normal color and the fallback color are clipped according to the ‘background-clip’ value associated with the bottom-most background image.

4.2 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. The ‘background-color’ is painted below all the images.

A value of ‘none’ counts as an image 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) has the same effect as ‘none’.

See the section “Layering multiple background images” for how each image is tiled or stretched.

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

4.3 The ‘background-repeat’ property

Specifies how images are tiled. The type <repeat> stands for: repeat-x | repeat-y | [repeat | space | round | no-repeat]{1,2}.

See the section “Layering multiple background images” for how each comma-separated value is applied to each image of the ‘background-image’ property.

The tiling and positioning of the background image on inline elements is described under the ‘background-break’ property.

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 area. The image is clipped at the border or padding edge (depending on ‘background-clip’).

no-repeat

The image is not repeated in this direction. If it is too large, the image is clipped at the border or padding edge (depending on ‘background-clip’).

space

The image is repeated as often as it will fit without being clipped and then the images are spaced out to fill the area. The first and last images touch the edges. 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 it will fit. If it doesn't fit a whole number of times, it is reduced in size until it does. See explanation under ‘background-size’.

Unless one of the two keywords is ‘no-repeat’, the whole background 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
}

4.4 The ‘background-attachment’ property

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

See the section “Layering multiple background images” for how each comma-separated value is applied to each image of the ‘background-image’ property.

The difference between ‘scroll’ and ‘local’ is only visible when the element has a scrolling mechanism (see ‘overflow’): in the case of ‘scroll’, the background does not scroll with the element's content. (It is attached to the element's border, as it were.) 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.

Even if the image is fixed, it is still only visible when it is in the content, padding, or border area of the element. 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;
}

4.5 The ‘background-position’ property

If background images have been specified, this property specifies their initial position. The section “Layering multiple background images” defines to which image of ‘background-image’ each of the comma-separated values applies.

The <bg-position> stands for: [ [ <percentage> | <length> | left | center | right ] [ <percentage> | <length> | top | center | bottom ]? ] | [ [ left | center | right ] || [ top | center | bottom ] ]

Each <bg-position> specifies an offset from the top left corner of either the viewport (if ‘background-attachment’ is ‘fixed’ for this image) or the box given by ‘background-origin’ (if ‘background-attachment’ is not ‘fixed’).

If only one percentage or length value is given, it sets the horizontal offset only, and the vertical offset will be 50%. If two values are given, the horizontal offset comes first. Combinations of keyword, length and percentage values are allowed, (e.g., ‘50% 2cm’ or ‘center 2cm’ or ‘center 10%’). For pairs of keyword and non-keyword values, ‘left’ and ‘right’ may only be used as the first value, and ‘top’ and ‘bottom’ may only be used as the second value. Negative positions are allowed.

The keywords are equivalent to percentages, as follows:

top left,

left top

Same as ‘0% 0%’.

top,

top center,

center top

Same as ‘50% 0%’.

right top,

top right

Same as ‘100% 0%’.

left,

left center,

center left

Same as ‘0% 50%’.

center,

center center

Same as ‘50% 50%’.

right,

right center,

center right

Same as ‘100% 50%’.

bottom left,

left bottom

Same as ‘0% 100%’.

bottom,

bottom center,

center bottom

Same as ‘50% 100%’.

bottom right,

right bottom

Same as ‘100% 100%’.

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

If the element is rendered as multiple boxes (e.g., inline boxes on several lines, boxes on several pages), the ‘background-break’ property determines which box(es) to use.

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: calc(100% - 3em) calc(100% - 10px)

4.6 The ‘background-clip’ property

Determines whether the background may extend into the padding and border areas. If the value is '‘padding-box’, the background is clipped to the padding box. If the value is ‘border-box’, the background is clipped to the border box. If the value is ‘content-box’, the background is clipped to the content box.

If the value is ‘no-clip’ and the background image is not repeated, then the image is not clipped. If the image is repeated, copies that are completely outside the border box are clipped, but copies that are partially inside it are not clipped. Background images may still be clipped by ‘overflow’ or by the viewport. A value of ‘no-clip’ clips the background color to the border box.

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

Each comma-separated value applies to one image of ‘background-image’. See the section “Layering multiple background images” for how clip values and images are paired.

4.7 The ‘background-origin’ property

Determines how the ‘background-position’ is calculated. With a value of ‘padding-box’, the position is relative to the padding box (‘0 0’ is the upper left corner of the padding edge, ‘100% 100%’ is the lower right corner). ''Border-box' means the position is relative to the border box, and ‘content-box’ means relative to the content box.

Each comma-separated value applies to one image of ‘background-image’. See the section “Layering multiple background images” for how origin values and images are paired.

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.

4.8 The ‘background-size’ property

Specifies the size of the background images. The section “Layering multiple background images” defines to which image of the ‘background-image’ property each of the comma-separated value segments applies. 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 rectangle given by ‘background-origin’.

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 rectangle given by ‘background-origin’.

<length> | <percentage> | auto [<length> | <percentage> | auto ]?

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 size of the area given by ‘background-origin’, except when the image's ‘background-attachment’ is ‘fixed’, in which case it is relative to the viewport. Should that be "initial containing block" to handle paged media?

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. A size of zero is allowed, but causes the image not to be displayed. (The effect is the same as if it had been a transparent image.)

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 }

4.9 The ‘background-break’ property

This property applies to inline flow elements (specifically, it does not apply to elements that are inline-block or inline-table), and to block-level elements when they are broken into several boxes (for example, across pages [CSS3PAGE]). The property does different things for different types of boxes.

For inline flow elements, values have the following meanings:

bounding-box

The background is drawn in a rectangle which is the smallest rectangle that encloses all inline boxes of the element. It is only visible within the padding (or border, depending on the ‘background-clip’ property) area of the inline boxes. If the boxes are on different pages, the pages are treated as one continuous page, glued together at their top and bottom (after stripping away the top and bottom page margins) and the rectangle is drawn on this continuous page.

each-box

The background is drawn in each inline box of the element. A no-repeat background image will thus be rendered once in each inline 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 one long row; the background is applied to the bounding box of this row and then the boxes are put back, with their share of the background. The order in the row is the visual order of the boxes, not the logical order of the source. I.e., in a right-to-left containing block ( ‘direction’ is ‘ltr’), the first box is the leftmost box on the first line and subsequent boxes 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. Is this true? or the direction of the element itself?

For block-level elements, values have the following meanings: (EDITOR'S NOTE: following needs to be checked against what was in old "background-break (open|close)" property)

bounding-box

The background is tiled in a rectangle which is the smallest rectangle that encloses all boxes of the block-level element.

each-box

Each box of the block-level element is treated separately for background rendering.

continuous

For block-level elements, ‘continuous’ works identical to ‘bounding-box’

4.10 Layering multiple background images

The properties ‘background-image’, ‘background-origin’, ‘background-clip’, ‘background-repeat’, ‘background-size’, and ‘background-position’ may have multiple comma-separated values. If the values are specified as follows:

background-image: w₁, w₂, w₃,…, w_M
background-repeat: x₁, x₂, x₃,…, x_R
background-size: y₁, y₂, y₃,…, y_S
background-position: s₁, s₂, s₃,…, s_P

then the number of layers is N = max(M, R, S, P)

Each of the properties is interpreted as if it had N values, by repeating the specified values like this:

background-image: w₁,…w_M, w₁,…w_M, w₁,… /* N values */
background-repeat: x₁,…x_R, x₁,…x_R, x₁,… /* N values */
background-size: y₁,…y_S, y₁,…y_S, y₁,… /* N values */
background-position: s₁,…r_P, s₁,…r_P, s₁,… /* N values */

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

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-image: url(red.png), url(blue.png);
background-repeat: repeat-x, repeat-y, repeat-y;
background-position: 20% 25%, 40% 10%, 50% 15%, 70% 40%, 90% 35%;

background-image: url(red.png), url(blue.png), url(red.png),
    url(blue.png), url(red.png);
background-repeat: repeat-x, repeat-y, repeat-y, repeat-x, repeat-y;
background-position: 20% 25%, 40% 10%, 50% 15%, 70% 40%, 90% 35%;

Each of the images is repeated, sized, and positioned according to the corresponding value in the other properties. The first image in the list is the layer closest to the user, the next one is painted behind the first, and so on.

4.11 The ‘background’ property

<bg-layer> stands for: < ‘background-image’> || < ‘background-position’> || / < ‘background-size’> || < ‘background-repeat’> || < ‘background-attachment’> || < ‘background-clip’> < ‘background-origin’>? where ''/ < ‘background-size’>‘ must occur after ’<‘background-position’>'' if both are present.

<final-bg-layer> stands for: < ‘background-image’> || < ‘background-position’> || / < ‘background-size’> || < ‘background-repeat’> || < ‘background-attachment’> || [ < ‘background-clip’> < ‘background-origin’>? ] || < ‘background-color’> where ''/ < ‘background-size’>‘ must occur after ’<‘background-position’>'' 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. It sets each of ‘background-color’, ‘background-position’, ‘background-size’, ‘background-repeat’, ‘background-clip’, ‘background-origin’, ‘background-attachment’ and ‘background-image’ to the value given, or to its initial value, if no explicit value was specified. (It does not set ‘background-break’.)

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.

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.

4.12 The background of the canvas

The background of the root element becomes the background of the canvas and extends to cover the entire canvas, although any images are positioned and stretched relative to the root element as if they were painted for that element alone. If the root's background-color value is ‘transparent’, the color is UA dependent. The root element does not paint this background again.

For HTML documents, however, it is recommended that authors specify the background for the BODY element rather than the HTML element. User agents must observe the following precedence rules to fill in the background of the canvas of HTML documents: if either or both of the ‘background-image’ and ‘background-color’ properties on the HTML element is different from their initial values, then use the background of the HTML element, else use the background of the BODY element. This does not apply to XHTML documents.

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

5. Border properties

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

5.2 The ‘border-style’ properties

These properties set the style of the border, unless there is a border image (see ‘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.

<border-style> is: 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 conflict resolution rules for tables [CSS3TBL].

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. Different meaning on table[ref] elements.

outset

Looks as if the content on the inside of the border is coming out of the canvas. Different meaning for table[ref] elements.

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.

5.3 The ‘border-width’ properties

These properties set the thickness of the border.

The <border-width> is <length> | <percentage> | thin | medium | thick. The <length> and <percentage> 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.

Defining percentage borders is complicated for tables and would require defaulting to some value (medium?) in cases where the percentage cannot be resolved. Since we have no compelling use cases for percentage borders, we plan to drop percentage border-widths in the next draft.

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

5.4 The ‘border-image’ property

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

The up to four numbers or percentages immediately following the <uri> specify which part of that image is used for which part of the border. They divide the image into nine parts: four corners, four edges and a middle part. The middle part is used as an extra background image.

The first of the four values is the height of the top edge and of the two top corners. The second is the width of the right edge and the two right corners. The third is the height of the bottom edge and the two bottom corners. The fourth is the width of the left edge and the two left corners.

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 CSS px units (if not). Negative values are not allowed and values bigger than the size of the image are interpreted as 100%.

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.

If the slash is present in the property value, the one to four values after it are used for the width of the border instead of the ‘border-width’ properties (but only if the specified image can be displayed). The order of the values is the same as for ‘border-width’.

At the end of the value, there may be up to two keywords, that specify how the images for the sides and the middle part are scaled and tiled. If the second is absent, it is assumed to be the same as the first. If both are absent, the effect is the same as ‘stretch stretch’.

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 borders, respectively, (either using ‘border-width’ or the values specified after the slash) and their width is scaled proportionally.

• The images for the left and right edge are made as wide as the left and right borders, respectively, and their height is scaled proportionally.

• The corner images are scaled to be as wide and as tall as the two borders 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.

  Clarify that failing means factor is zero or infinity

step 2

• If the first keyword is ‘stretch’, the top, middle and bottom images are further scaled to be as wide as the element's padding box. 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 width of the padding box, 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 (the middle image is put in the padding 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/padding 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 behind the element's content, in front of the element's background.

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

The ‘border-image’ property does not apply to table elements in a table with ‘border-collapse’ set to ‘collapse’.

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

If the first value is a percentage, it is relative to the width of the border box. If the second value is a percentage, it is relative to the height of the border box. If the first value is a percentage and the second value is omitted, the percentage is relative to the width, resp., height of the border box, depending on whether ‘block-progression’ is ‘tb’ or not.

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

Backgrounds, but not the border-image, are clipped to the inner, resp., outer curve of the border if ‘background-clip’ is ‘padding-box’ resp., ‘border-box’. Other effects that clip to the border or padding edge (such as ‘overflow’) also must clip to the curve.

When two adjoining borders are of different thicknesses the corner will show a smooth transition between the thicker and thinner borders. One of the borders may even have zero width.

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.

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 adjoining radii may not be more than the width or height (whichever is relevant) of the box. If any sum exceeds that value, 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

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 }

5.6 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 style is set to ‘none’, no border and no padding are inserted.

Otherwise, padding is added as wide as the corresponding side of the ‘padding’ property and a border is added. If borders on that side would get an image, the image is used, scaled to the given width, otherwise the border gets the given style and color.

Note that, unlike for the other borders of the element, a value of ‘none’ suppresses any image border as well. If you want an image or nothing, use ‘hidden’ instead.

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

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

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

5.8 The ‘box-shadow’ property

One or more drop-shadows can be attached to a box. The property is a comma-separated list of shadows, each specified by 4 length values and a color. Omitted lengths are 0, omitted colors are a UA-chosen color.

The 4 lengths and the color 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 by the specified radius. Negative values cause the shadow to shrink.
• The color is the color of the shadow.

A box-shadow shadows the border-box of the element as if it were opaque. If the box has a nonzero ‘border-radius’, the shadow is rounded in the same way. The shadow is drawn outside the border edge only: it is not drawn inside the border-box of the element. 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’.

Shadows do not influence the layout: they may overlap with other boxes. Like backgrounds and borders, if they overlap other boxes, they are drawn behind any text or replaced element. In terms of the stacking context, the shadow of an element is drawn immediately below the background of that element.

span {border: thin solid; box-shadow: 0.2em 0.2em #CCC}

6. Definitions

6.1 Profiles

(NOTE: Check profiles because of changes made!)

CSS1 Profile:

• ‘background-color’
• ‘background-image’
• ‘background-repeat’: only repeat, repeat-x, repeat-y, no-repeat
• ‘background-attachment’
• ‘background-position’
• ‘background’: only color, image, repeat, attachment and position
• ‘background-origin’ always has value ‘content-box’
• ‘background-clip’ always has value ‘border-box’
• ‘background-break’ always has value ‘continuous’

CSS2 Profile:

• ‘background-color’
• ‘background-image’
• ‘background-repeat’: only repeat, repeat-x, repeat-y, no-repeat
• ‘background-attachment’
• ‘background-position’
• ‘background’: only color, image, repeat, attachment and position
• ‘background-origin’ always has value ‘padding-box’
• ‘background-clip’ always has value ‘border-box’
• ‘background-break’ always has value ‘continuous’

Mobile and TV Profiles (informative, see their specifications):

• ‘background-color’
• ‘background-image’
• ‘background-repeat’: only repeat, repeat-x, repeat-y, no-repeat
• ‘background-position’
• ‘background’: only color, image, repeat and position
• ‘background-attachment’: always has value ‘scroll’
• ‘background-origin’ always has value ‘padding-box’
• ‘background-clip’ always has value ‘border-box’
• ‘background-break’ always has value ‘continuous’

CSS3 Profile:

• Everything (as described in this specification)

6.2 Conformance

A UA conforms to this module if it satisfies the rules given next. However, it is recommended that UAs try to conform to one of the levels (1, 2 or 3) or profiles ([CSS-MOBILE], [CSS-PRINT], etc.) of CSS, rather than to individual modules.

A UA that renders documents must interpret CSS style sheets according to the generic CSS grammar [CSS3SYN] and the individual grammars of each property in this module, it must understand at least type selectors [SELECT], it must apply the rules of cascading and inheritance [CSS3CASCADE], and it must render documents as defined for each property in this module.

A UA that writes style sheets, must write syntactically correct style sheets, according to the generic CSS grammar [CSS3SYN] and the individual grammars of each property in this module.

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 cannot render color on a monochrome monitor.)

6.3 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

source document

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

HTML document

A document that has the MIME type text/html [RFC2854] and conforms to that type.

XHTML document

A document that has the MIME type text/xhtml+xml or application/xhtml+xml [RFC3236] and conforms to either type.

style sheet

A document conforming to the generic CSS grammar [CSS3SYN].

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:

1. There must be at least two interoperable implementations for every feature in the Module. For the purposes of this criterion, we define the following terms:

   feature

   a section or subsection of the specification

   interoperable

   passing the respective test case(s) in the CSS test suite, or, if the implementation is not a web browser, an equivalent test. Every relevant test in the test suite should have an equivalent test created if such a UA is to be used to claim interoperability. In addition if such a UA is to be used to claim interoperability, then there must one or more additional UAs which can also pass those equivalent tests in the same way for the purpose of interoperability. The equivalent tests must be made publicly available for the purposes of peer review.

   implementation

   a user agent which:

   1. implements the feature.
   2. is available (i.e. publicly downloadable or available through some other public point of sale mechanism). This is the "show me" requirement.
   3. is shipping (i.e. development, private or unofficial versions are insufficient).
   4. is not experimental (i.e. is intended for a wide audience and could be used on a daily basis.)

2. A minimum of sixth months of the CR period must have elapsed. This is to ensure that enough time is given for any remaining major errors to be caught.

3. Features will be dropped if two or more interoperable implementations are not found by the end of the CR period.

4. Features may/will also be dropped if adequate/sufficient (by judgment of CSS WG) tests have not been produced for those feature(s) by the end of the CR period.

7. Acknowledgments

Tapas Roy was editor of the Border Module, before it was merged with the Background Module.

A set of properties for border images was initially proposed by fantasai. The current simplification (one image cut into nine parts) is due to Ian Hickson. (Though the original idea seems to originate with some anonymous Microsoft engineers.)

Thanks to Ben Stucki for defining what happens with rounded corners if the two adjoining borders are of unequal thickness or one of them is zero; to Arjan Eising and Anne van Kesteren for the ‘border-radius’ syntax.

Emrah Baskaya and Simon Pieters were among the people who argued for a fallback color (see ‘backgound-color’), which is only shown when any specified image(s) cannot be loaded.

8. References

Normative references

[CSS21]

Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 19 July 2007. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2007/CR-CSS21-20070719

[CSS3BOX]

Bert Bos. CSS basic box model. 9 August 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-css3-box-20070809

[CSS3CASCADE]

Håkon Wium Lie. CSS3 module: Cascading and inheritance. 15 December 2005. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2005/WD-css3-cascade-20051215

[CSS3COLOR]

Tantek Çelik; Chris Lilley. CSS3 Color Module. 14 May 2003. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2003/CR-css3-color-20030514

[CSS3PAGE]

Håkon Wium Lie; Melinda Grant. CSS3 Module: Paged Media. 10 October 2006. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2006/WD-css3-page-20061010

[CSS3SYN]

L. David Baron. CSS3 module: Syntax. 13 August 2003. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2003/WD-css3-syntax-20030813

[CSS3VAL]

Håkon Wium Lie; Chris Lilley. CSS3 Values and Units. 19 September 2006. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2006/WD-css3-values-20060919

[SELECT]

Daniel Glazman; Tantek Çelik; Ian Hickson. Selectors. 15 December 2005. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2005/WD-css3-selectors-20051215

Other references

[CSS-MOBILE]

Svante Schubert. CSS Mobile Profile 2.0. 19 October 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-css-mobile-20071019

[CSS-PRINT]

Melinda Grant. CSS Print Profile. 13 October 2006. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2006/WD-css-print-20061013

[CSS1]

Håkon Wium Lie; Bert Bos. Cascading Style Sheets (CSS1) Level 1 Specification. 17 December 1996. W3C Recommendation. Revised 11 January 1999. URL: http://www.w3.org/TR/1999/REC-CSS1-19990111

[CSS3TBL]

Bert Bos; David Hyatt. CSS3 Tables Module. (forthcoming). W3C Working Draft. (Work in progress.)

[CSS3TEXT]

Elika J. Etemad; Paul Nelson. CSS Text Level 3. 6 March 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-css3-text-20070306

[CSS3VAL]

Håkon Wium Lie; Chris Lilley. CSS3 Values and Units. 19 September 2006. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2006/WD-css3-values-20060919

[RFC2854]

D. Connolly; L. Masinter. The 'text/html' Media Type. June 2000. Internet RFC 2854. URL: http://www.rfc-editor.org/rfc/rfc2854.txt

[RFC3236]

P. Stark; M. Baker. The 'application/xhtml+xml' Media Type. January 2002. Internet RFC 3236. URL: http://www.rfc-editor.org/rfc/rfc3236.txt

[XML11]

Tim Bray; et al. Extensible Markup Language (XML) 1.1 (Second Edition). 4 February 2004. W3C Recommendation. Revised 29 September 2006 URL: http://www.w3.org/TR/2006/REC-xml11-20060816

Property index