W3C

CSS3 module: Border

W3C Working Draft 7 November 2002

This version:
http://www.w3.org/TR/2002/WD-css3-border-20021107
Latest version:
http://www.w3.org/TR/css3-border
Previous versions:
none
Editors:
Tapas Roy (Openwave)

Abstract

CSS (Cascading Style Sheets) is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc. This draft describes the functionality that is proposed for CSS level 3 to describe borders, such as border styles, border colors and border images. It includes and extends the functionality of CSS level 2 [CSS2], which builds on CSS Level 1 [CSS1].

Status of this document

This document is a draft of one of the "modules" [CSS3-intro] for the upcoming CSS3 specification. It not only describes the border functionality that already exists in CSS1 and CSS2, but also proposes new functionality for CSS3 as well as for other languages that may need it.

This document is a working draft of the CSS working group which is part of the style activity (see summary).

Comments on, and discussions of this draft can be sent on the (archived) public mailing list www-style@w3.org (see instructions). W3C Members can also send comments directly to the CSS working group.

This is a working draft and may therefore be updated, replaced or rendered obsolete by other W3C documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". Its publication does not imply endorsement by the W3C membership or the CSS Working Group (members only).

Patent disclosures relevant to CSS may be found on the Working Group's public patent disclosure page.

To find the latest version of this working draft, please follow the "Latest version" link above, or visit the list of W3C Technical Reports.

This document may be available in translations in the future. The English version of this specification is the only normative version.

Table of contents

1. Dependencies with other CSS 3 Modules

2. Context

Members of the CSS Working Group proposed during the Clamart meeting to modularize the CSS specification.

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

This specification will contain its own test cases, one test per concept introduced in this document. These tests will not be conformance full tests but will be intended to provide users with a way to check if a part of this specification is implemented at least a minima or not or, on the contrary, not implemented at all.

3. The Border

3.1 The 'border-color' properties

Name: border-top-color , border-right-color, border-bottom-color, border-left-color
Value: <color>
Initial: the value of the 'color' property
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: <color>
Name: border-color
Value: <border-color>{1,4}
Initial: (see individual properties)
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: see individual properties

'Border-color' is a shorthand for the four 'border-*-color' properties.

When the border color is 'transparent', only the background is visible.

The background of the element extends into the border area. See the 'background' property.

3.2 The 'border-style' properties

Name: border-top-style , border-right-style, border-bottom-style, border-left-style
Value: <border-style>
Initial: none
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified value
Name: border-style
Value: <border-style>{1,4}
Initial: (see individual properties)
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: see individual properties

<border-style> is 'none | hidden | dotted | dashed | solid | double | dot-dash | dot-dot-dash | wave | groove | ridge | inset | outset', with the following meanings:

none
No border. Color and width are ignored (i.e., the border has width 0).
hidden
Same as 'none', but has different behavior in the conflict resolution rules for tables[ref].
dotted
A series of dots.
dashed
A series of 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'.)
dot-dash
Alternating dots and dashes.
dot-dot-dash
Two dots and a dash.
wave
A wavy line.
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.

'Border-style' is a shorthand that sets the four 'border-*-style' properties.

Examples of border styles

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.

3.3 The 'border-radius' properties

Name: border-top-right-radius, border-bottom-right-radius, border-bottom-left-radius, border-top-left-radius, border-radius
Value: <length> <length>?
Initial: 0
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values

The two length values of the 'border-radius' properties define the radii of a quarter ellipse that defines the shape of the corner (see the diagram below). The first value is the horizontal radius (or vertical if the 'writing-mode' is vertical). 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 also causes the element's background to be rounded (even if the border is 'none'). Negative values are not allowed.

Diagram of the inscribed ellips

3.4 The Border Image properties

The border-image properties allow the author to assign images to borders. There are four groups of border image properties:

Specifying border images
These properties are used to specify the URI of the border image.
Fitting border images
These properties are used to specify how the image(s) are fitted in the border area.
Transforming border images
These properties are used to make the images of a side or a corner to be reflected or rotated versions of another.

The border image properties override the border style properties.

3.4.1 The 'border-image' properties

The border image is specified as a URI, for two different groups:

Border edge images
The URI of upto three images may be specified for each of the four border edges. If one image URI is given, the first tile is centered on the border line. If two image URIs are given, they meet at the center of the border line with the first image placed on the top or left side of the center. If three image URIs are given, the second becomes the center and does not tile. The other two are placed on either side of the center image, with the first going on the top or left side of the center and the third going on the bottom or right.
Border corner images
Separate images may be specified for each of the four border corners. The outer corner of the image is aligned with the outer corner of the border's corner area. If the border corner image is set to 'continue', then no image is assigned, and the border image area extends through the corner area to the border edge. The two sides are clipped at an angle to form a mitered corner. The area of the corner is determined by the perpendicular corner radii and the outer border edge lines or by extending perpendiculars from the padding edge corner, whichever yields a greater area.
Name: border-top-image , border-right-image, border-bottom-image, border-left-image
Value: <uri> {1,3}| none | inherit
Initial: none
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values
Name: border-image
Value: [<uri> | none] {1,4} | inherit
Initial: none
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified value

'border-image' is a shorthand for 'border-top-image', 'border-right-image', 'border-bottom-image' and 'border-left-image' properties.

Name: border-top-left-image , border-top-right-image, border-bottom-right-image, border-bottom-left-image
Value: <uri>| continue | none | inherit
Initial: continue
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values
Name: border-corner-image
Value: [<uri> | continue] | [<uri> | continue] {1,4} | none | inherit
Initial: continue
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified value

'border-corner-image' is a shorthand propery for 'border-top-left-image', 'border-top-right-image', 'border-bottom-right-image' and 'border-bottom-left-image' properties.

An example of doing border-image with eight images.

border-image example

3.4.2 The 'border-fit' properties

The border-fit properties determine if and how the border image(s) will tile. Meanings are as follows:

clip
Place one tile without scaling and clip overflow.
repeat
Repeat the image until it fills the border area and clip any overflow.
scale
Repeat the image as close to filling the area as possible and scale all tiles up or down as necessary to fill the area without overflow.
stretch
Stretch (or shrink) the image so one tile covers the whole area.
overwrite
Place a single tile without scaling and don't clip overflow.
overflow
Repeat the image as many times as necessary to fill the area and don't clip overflow.
space
Repeat the image as close to filling the area as possible without overflowing, and space images out so that the tiling fills the area exactly.

The border-fit properties are grouped into the 'border-fit-length' and the 'border-fit-width' properties. The 'border-fit-length' properties determine image handling in the border's length dimension, that is, horizontally for the top and bottom borders and vertically for the left and right borders. The 'border-fit-width' properties determine image handling in the border's width dimension, that is, vertically for the top and bottom borders and horizonatally for the left and right borders.

For the overwrite and overflow values of border-fit, the image may overflow into the content area, but it has to be clipped at the opposite edge of the content area.

Name: border-top-fit-length , border-right-fit-length, border-bottom-fit-length, border-left-fit-length, border-top-fit-width , border-right-fit-width, border-bottom-fit-width, border-left-fit-width
Value: [clip | repeat | scale | stretch | overwrite | overflow | space ] {1,2}
Initial: repeat
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values

If the border-image property specified a center image, then the second value applies to that image. Otherwise, it is ignored.

Name: border-fit-length , border-fit-width
Value: <border-fit>{1,4}
Initial: repeat
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values
Name: border-fit
Value: <border-fit> <border-fit>?
Initial: repeat
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values

The second value in 'border-fit', if present, applies to the width. If there is only one value, it sets both border-fit-width and border-fit-length

Name: border-top-left-fit-length , border-top-right-fit-length, border-bottom-right-fit-length, border-bottoml-eft-fit-length, border-top-left-fit-width , border-top-right-fit-width, border-bottom-right-fit-width, border-bottom-left-fit-width
Value: [clip | repeat | scale | stretch | overwrite | overflow | space ] {1,2}
Initial: overwrite
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values

These properties determines border corner image handling. If a second value is present, it applies to the horizontal dimension.

Name: border-corner-fit
Value: <border-fit>| <border-fit> {2} | <border-fit>{4}
Initial: overwrite
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values

If one value is present in the 'border-corner-fit' shorthand property, it sets the border-corner-fit for all corners. If two values are present, the second value applies to the horizontal dimension. If four values are present, they set both dimensions for the top left, top right, bottom right, and bottom left corners respectively.

3.4.3 The 'border-image-transform' properties

These properties are used to specify that an image on the corner is a transform of the border-top-left-image or the images on the edge is a transform of border-top-image and border-left-image.

The possible transforms on the corner images are:

none
Place the image without modification.
rotate
Rotate the image so that the side that would face the inner edge if it were placed on the top border remains facing the inner edge.
reflect
Flip the image so the sides that would be the inner edges of the image were it placed in the top left corner remain the inner sides.

The possible transforms on the edge images are:

none
Place the image without modification.
rotate
Rotate the image so that the side that would face the inner edge if it were placed on the top border remains facing the inner edge.
reflect-xy
The image is assumed to be designed for the top or left sides. The right border image is reflected across a vertical axis and the bottom border image is reflected across a horizontal one.
reflect-right
The image is assumed to be designed for the top border. The right border image is rotated 90 degrees to the right; the left border image is rotated 90 degrees to the right and reflected across a vertical axis. The bottom border image is reflected across a horizontal axis.
reflect-left
The image is assumed to be designed for the top border. The left border image is rotated 90 degrees to the left. The right border image is rotated 90 degrees to the left and reflected across a vertical axis. The bottom border image is reflected across a horizontal axis.
Name: border-corner-image-transform
Value: none | rotate | reflect
Initial: none
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values
Name: border-image-transform
Value: none | rotate | reflect-xy | reflect-right | reflect-left
Initial: none
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified values

3.5 The 'border-break' property

Name: border-break
Value: <border-style>
Initial: none
Applies to: elements with a border
Inherited: yes
Percentages: N/A
Media: visual
Computed value: specified value

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 can be inserted at the break, or the border can be left open. A border-style or a border-image will add padding and a border at the break, as if it was the normal end of the box. The value 'none' will not add padding or border at the break. The property has no effect if the border is absent.

Illustration of border-break

3.6 The 'box-shadow' property

Name: box-shadow
Value: none | [ <length> <length> <length>? || <color> ] [ , <length> <length> <length>? || <color> ]+
Initial: none
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: absolute values

One or more drop-shadows can be attached to a box. They are drawn just outside the border. The property is a comma-separated list of shadows, each specified by 3 length values and a color. Omitted lengths are 0, omitted colors are equal to the computed value of the 'color' property.

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.

The 3 lengths and the color of each shadow are interpreted as follows:

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'. If the box has a non-zero border-radius', the shadow is rounded in the same way.

Here is an example of single words with a drop shadow. Assume the words were enclosed in <span> and the style rule was

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

The result might look like this:

He will be put on b_r_e_a_d_| and w_a_t_e_r_|

3.7 The border shorthand properties: 'border-top', 'border-bottom', 'border-right', 'border-left', and 'border'

Name: 'border-top', 'border-right', 'border-bottom', 'border-left'
Value: [ <border-width> || <border-style> || [<color> | transparent] || <uri>]| inherit
Initial: See individual properties
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: absolute values
This is a shorthand property for setting the width, style, color and the image of the top, right, bottom, and left border of a box. Ommitted values are set to their initial values. Although the border-image property overrides the border-style property, but for backward compatibility with CSS 2, and the browsers that support the CSS 2 border shorthand properties, authors are encouraged to use:
h1 { border-bottom: thick solid red url('lines.jpg')}
or
h1 { border-bottom: thick none transparent url('wavyredline.jpg') }
Name: 'border'
Value: [ <border-width> || <border-style> || [<color> | transparent] || [<uri> <border-image-transform>?]] | inherit
Initial: See individual properties
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: absolute values
The 'border' property is a shorthand property for setting the same width, color, style and images for all four borders of a box. Moreover, a border-image transform maybe specified with a border image. 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.

For example, the first rule below is equivalent to the set of four rules shown after it:

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.

Consider this example:

blockquote {
  border-color: red;
  border-left: double;
  color: black
}
In the above example, the color of the left border is black, while the other borders are red. This is due to 'border-left' setting the width, style, and color. Since the color value is not given by the 'border-left'property, it will be taken from the 'color' property. The fact that the 'color' property is set after the 'border-left'property is not relevant.

4. Profiles

A Basic Profile of the border module includes support for the following properties:

5. Conformance

This section will define conformance with the present specification only.

The inability of a user agent to implement part of this specification due to the limitations of a particular device does not imply non-conformance.

User agents must observe the rules for handling parsing errors.

6. Tests

This specification will contain a test suite allowing user agents to verify their basic conformance to the specification. This test suite does not pretend to be exhaustive and does not cover all possible combined cases of W3C background functionality.

7. Acknowledgements

The author would like to thank fantasai for providing the proposal for the border image properties. The author would like to thank Tantek Çelik for pointing out the need for border image transform properties.

8. References

Normative references

[CSS3-box]
Bert Bos. CSS3 module: box model. 26 July 2001. W3C working draft. (Work in progress.) URL: http://www.w3.org/TR/2001/WD-css3-box-20010726
[CSS3-cascade]
Håkon Wium Lie. CSS3 module: Cascading and inheritance. 13 July 2001. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2001/WD-css3-cascade-20010713
[CSS3-color]
Tantek Çelik; Chris Lilley. CSS3 module: color. 5 March 2001. W3C working draft. (Work in progress.) URL: http://www.w3.org/TR/2001/WD-css3-color-20010305
[CSS3-syntax]
David Baron. CSS3 module: syntax. (forthcoming). W3C working draft. (Work in progress.)
[CSS3-values]
Håkon Wium Lie. CSS3 module: values and units. (forthcoming). W3C working draft. (Work in progress.)

Other references

[CSS1]
Håkon Wium Lie; Bert Bos. Cascading Style Sheets, level 1. 1996. W3C Recommendation. Revised 11 Jan 1999. URL: http://www.w3.org/TR/REC-CSS1
[CSS2]
Bert Bos; Håkon Wium Lie; Chris Lilley; Ian Jacobs. Cascading Style Sheets, level 2. 1998. W3C Recommendation. URL: http://www.w3.org/TR/REC-CSS2
[CSS3-intro]
Eric A. Meyer; Bert Bos. Introduction to CSS3. 23 May 2001. W3C working draft. (Work in progress.) URL: http://www.w3.org/TR/css3-roadmap

Property index

Property Values Initial Applies to Inh. Percentages Media
border-color border-top-color, border-right-color, border-bottom-color, border-left-color <color> the value of the 'color' property all elements no N/A visual
border-style border-top-style, border-right-style, border-bottom-style, border-left-style <border-style> none all elements no N/A visual
border-top-right-radius border-bottom-right-radius, border-bottom-left-radius, border-top-left-radius, border-radius <length> <length>? 0 all elements no N/A visual
border-top-image, border-right-image, border-bottom-color, border-left-image <uri> {1,3}| none | inherit none all elements no N/A visual
border-image [<uri> | none] {1,4} | inherit none all elements no N/A visual
border-top-left-image, border-top-right-image, border-bottom-right-color, border-bottom-left-image <uri>| continue | none | inherit continue all elements no N/A visual
border-corner-image [<uri> | continue] | [<uri> | continue] {1,4} | none | inherit none all elements no N/A visual
border-top-fit-length, border-right-fit-length, border-bottom-fit-length, border-left-fit-length border-top-fit-width, border-right-fit-width, border-bottom-fit-width, border-left-fit-width [clip | repeat | scale | stretch | overwrite| overflow | space ] {1,2} repeat all elements no N/A visual
border-fit-length border-fit-width <border-fit>{1,4} repeat all elements no N/A visual
border-fit <border-fit> <border-fit>? repeat all elements no N/A visual
border-top-left-fit-length, border-top-right-fit-length, border-bottom-right-fit-length, border-bottom-left-fit-length border-top-left-fit-width, border-top-right-fit-width, border-bottom-right-fit-width, border-bottom-left-fit-width [clip | repeat | scale | stretch | overwrite| overflow | space ] {1,2} overwrite all elements no N/A visual
border-corner-fit <border-fit>| <border-fit> {2} | <border-fit>{4} overwrite all elements no N/A visual
border-image-transform none | rotate | reflect-xy | reflect-right | reflect-left none all elements no N/A visual
border-break <border-style> none elements with a border yes N/A visual
box-shadow none | [ <length> <length> <length>? || <color> ] [ , <length> <length> <length>? || <color> ]+ none all elements no N/A visual
border-top, border-right, border-bottom, border-left [ <border-width> || <border-style> || [<color> | transparent] || <uri>]| inherit See individual properties all elements no N/A visual
border [ <border-width> || <border-style> || [<color> | transparent] || [<uri> <border-image-transform>?]] | inherit See individual properties all elements no N/A visual

The following properties are defined in other modules: