GeezerVison is showing drafts.csswg.org (truncated) — CSS Backgrounds and Borders Module Level 3
1. Introduction
This subsection is not normative.
When elements are rendered according to the
CSS box model[CSS-BOX-3],
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 various areas and edges of a typical box.
(This diagram is explained in the CSS Box Model Module [CSS-BOX-3].)
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 box fragments,
box-decoration-break[CSS-BREAK-3] defines
how the borders and background are divided over the various fragments.
(An element can result in more than one fragment 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 [CSS2].
1.1.
Module Interactions
This module replaces and extends the background and border features
defined in [CSS2] sections 8.5 and 14.2.
In addition to the property-specific values listed in their definitions,
all properties defined in this specification
also accept the CSS-wide keywords as their property value.
For readability they have not been repeated explicitly.
2.
Backgrounds
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.
2.1.
Layering Multiple Background Images
The background of a box can have multiple
background image layers.
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 background 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.
For example, this set of declarations:
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;
has exactly the same effect as this set,
with the extra position dropped
and the missing values for background-origin and background-repeat
filled in (emphasized for clarity):
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, 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: The border-image properties
can also define a background image,
which, if present, is painted on top of
the background layers created by the background properties.
This property specifies 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 property’s value is given as a comma-separated list
of <bg-image> values where
A value of none
counts as a background 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.
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.
For accessibility reasons,
authors should not use background images
as the sole method of conveying important information.
See Web Content Accessibility Guideline F3[WCAG20].
Images are not accessible in non-graphical presentations,
and background images specifically
might be turned off in high-contrast display modes.
Note: Stylistic foreground images can be provided in CSS
with the content property.
Semantically-important foreground images should be provided
in the document markup, e.g. with the <img> tag in HTML.
Note:Media fragments
can be used to display a portion of an image.
The CSS Images module
will provide fallback syntax for image formats
and include additional controls for image display.
Some examples specifying background images:
html { background-image: url("marble.svg") }
p { background-image: none }
div { background-image: url(tl.png), url(tr.png) }
main { background-image: radial-gradient(at bottom right, transparent, white); }
Implementations may optimize
by not downloading and drawing images that are not visible
(e.g., because they are behind other, fully opaque images).
This property specifies how background images are tiled
after they have been sized
and positioned.
The property’s value is given as a comma-separated list
of <repeat-style> values where
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 axis,
in which case only one image is placed,
and background-position determines its position in this axis.
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 rescaled so that it does.
See the formula 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.
no-repeat
The image is placed once and not repeated in this direction.
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;
}
The effect of repeat-y:
One copy of the background image is centered,
and other copies are put above and below it
to make a vertical band behind the element.
body {
background-image: url(dot.png) white;
background-repeat: space
}
The effect of space:
the image of a dot is tiled to cover the whole background
and the images are equally spaced.
If background images are specified,
this property specifies whether they are
fixed with regard to the viewport (fixed)
or scroll along with the box (scroll)
or its contents (local).
The property’s value is given as a comma-separated list
of <attachment> keywords where
The background is fixed with regard to the viewport.
In paged media where there is no viewport,
a fixed background is fixed with respect to
the page box
and therefore replicated on every page.
Note: There is only one viewport per view.
Even if an box is a scroll container,
a fixed background doesn’t move with the box.
The background is fixed with regard to the box itself
and does not scroll with its contents.
(It is effectively attached to the box’s border.)
Even if the image is fixed,
it is still only visible when it is in the background painting area of the box
or otherwise unclipped.
(See § 2.11 Backgrounds of Special Elements for the cases when
background images are not clipped.)
Thus, unless the image is tiled, it may be invisible.
This example creates an infinite vertical band
that remains “glued” to the viewport when the document is scrolled.
body {
background: red url("pendant.gif");
background-repeat: repeat-y;
background-attachment: fixed;
}
Note: User agents that do not support fixed backgrounds
(for example due to limitations of the hardware platform)
will 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;
}
If only one value is specified,
the second value is assumed to be center.
If two values are given,
a <length-percentage> as the first value represents
the horizontal position (or offset)
and a <length-percentage> as the second value represents
the vertical position (or offset).
The <length-percentage> values here represent
an offset of the top left corner of the background image
from the top left corner of the background positioning area.
Note: A pair of keywords can be reordered,
while a combination of keyword and length or percentage cannot.
So center left is valid while 50% left is not.
If three or four values are given,
then each <length-percentage> 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.
The following declarations give the stated (horizontal, vertical)
offsets from the top left corner:
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 */
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%.
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.
Computes to 50% (left 50%) for the horizontal position
if the horizontal position is not otherwise specified,
or 50% (top 50%) for the vertical position if it is.
The following background shorthand declarations use keywords
to set background-position to the stated percentage values.
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% */
In the example below, the (single) image is placed
in the lower-right corner of the viewport.
Background positions can also be relative to other corners than the top left.
For example, the following puts the background image
10px from the bottom and 3em from the right:
The specified value and computed value of the <bg-position> type
serialize exactly as defined in [CSS-VALUES-4] for <position>.
For 3-value productions
(which are not valid in <position>),
the specified value serialization
is identical to the equivalent 4-value syntax
except that the omitted offset remains omitted.
This property determines the background positioning area:
the area within which any background images are positioned.
For elements rendered as multiple box fragments
(e.g., inline boxes on several lines, boxes on several pages),
specifies which boxes box-decoration-break[CSS-BREAK-3] operates on
to determine the background positioning area(s).
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.)
An auto value for one dimension
is resolved by using the image’s natural aspect ratio
and the size of the other dimension,
or failing that, using the image’s natural size,
or failing that, treating it as 100%.
If both values are auto
then the natural 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 natural size,
its size is determined as for contain.
Negative values are invalid.
Here are some examples.
The first example stretches the background image
independently in both dimensions
to completely cover the content area:
The second example stretches the image
so that exactly two copies fit horizontally.
The aspect ratio is preserved:
p {
background-image: url(tubes.png);
background-size: 50% auto;
background-origin: border-box }
This example forces the background image to be 15 by 15 pixels:
p {
background-size: 15px 15px;
background-image: url(tile.png)}
This example uses the image’s natural size.
Note that this is the only possible behavior in CSS level 1 and 2.
body {
background-size: auto; /* default */
background-image: url(flower.png) }
The following example rounds the height of the image to 33.3%,
up from the specified value of 30%.
At 30%, three images would fit entirely and a fourth only partially.
After rounding, three images fit exactly.
The width of the image is 20% of the background positioning area width
and is not rounded.
If background-repeat is round
for one (or both) dimensions,
there is a second step.
The UA must scale the image in that dimension (or both dimensions)
so that it fits a whole number of times in the background positioning area.
In the case of the width (height is analogous):
If X ≠ 0 is the width of the image after step one
and W is the width of the background positioning area,
then the rounded width
X' = W / round(W / X)
where round() is a function that returns the nearest natural number
(integer greater than zero).
If background-repeat is round for one dimension only
and if background-size is auto for the other dimension,
then there is a third step:
that other dimension is scaled so that the original aspect ratio is restored.
In this example the background image is shown at its natural size:
div {
background-image: url(image1.png);
background-repeat: repeat; /* default */
background-size: auto } /* default */
In the following example, the background is shown with a width of
3em and its height is scaled proportionally to keep the original
aspect ratio:
In the following example,
the background is shown with a width of approximately 3em:
scaled so that it fits a whole number of times in the width of the background.
The height is scaled proportionally to keep the original aspect ratio:
div {
background-image: url(image3.png);
background-repeat: round repeat;
background-size: 3em auto }
In the following example, the background image is shown
with a width of 3em and a height that is either
the height corresponding to that width at the original aspect ratio
or slightly less:
div {
background-image: url(image4.png);
background-repeat: repeat round;
background-size: 3em auto }
In the following example,
the background image is shown with a height of approximately 4em:
scaled slightly so that it fits a whole number of times in the background height.
The width is the approximately the width that corresponds to
a 4em height at the original aspect ratio:
scaled slightly so that it fits a whole number of times
in the background width.
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.)
If one <visual-box> value is present
then it sets both background-origin and background-clip to that value.
If two values are present,
then the first sets background-origin and the second background-clip.
In the first rule of the following example, only a value for
background-color has been given and the
other individual properties are set to their initial values. In the
second rule, many individual properties have been specified.
body { background: red }
p { background: url("chess.png") 40% / 10em gray
round fixed border-box; }
The following example shows how a both
a background color (#CCC) and a background image (url(metal.jpg))
are set.
The image is rescaled to the full width of the element:
E { background: #CCC url("metal.jpg") top left / 100% auto no-repeat}
Another example shows equivalence:
div { background: padding-box 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 }
The following declaration with multiple, comma-separated values
background: url(a.png) top left no-repeat,
url(b.png) center / 100% 100% no-repeat,
url(c.png) white;
is equivalent to
background-image: url(a.png), url(b.png), url(c.png);
background-position: top left, center, top left;
background-repeat: no-repeat, 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;
2.11.
Backgrounds of Special Elements
The document canvas
is the infinite surface over which the document is rendered. [CSS2]
Since no element corresponds to the canvas,
in order to allow styling of the canvas
CSS propagates the background of the root element
(or, in the case of HTML, the <body> element)
as described below.
However, if the element whose background would be used for the canvas
is display: none,
then the canvas background is transparent.
If the canvas background is not opaque,
the canvas surface below it shows through.
The texture of the canvas surface is UA-dependent
(but is typically an opaque white).
2.11.1.
The Canvas Background and the Root Element
The background of the root element becomes the canvas background
and its background painting area extends
to cover the entire canvas.
However, any images are sized and positioned relative to the root element’s box
as if they were painted for that element alone.
(In other words, the
background positioning area
is determined as for the root element.)
The root element does not paint this background again,
i.e., the used value of its background is transparent.
2.11.2.
The Canvas Background and the HTML <body> Element
For documents whose root element is
an HTML HTML element
or an XHTML html element [HTML]:
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 XHTML 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
using the BODY element
rather than the HTML element.
According to these rules, the canvas underlying the following HTML document
will have a “marble” background:
<!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>
2.11.3.
The ::first-line Pseudo-element‘s Background
The ::first-line pseudo-element
is like an inline-level element
for the purposes of the background
(see section 5.12.1 of [CSS2]).
That means, e.g., that in a left-justified first line,
the background does not necessarily extend
all the way to the right edge.
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.
If there is only one component value,
it applies to all sides.
If there are two values,
the top and bottom are set to the first value
and the right and left are set to the second.
If there are three values,
the top is set to the first value,
the left and right are set to the second,
and the bottom is set to the third.
If there are four values
they apply to the top, right, bottom, and left, respectively.
If there is only one component value,
it applies to all sides.
If there are two values,
the top and bottom are set to the first value
and the right and left are set to the second.
If there are three values,
the top is set to the first value,
the left and right are set to the second,
and the bottom is set to the third.
If there are four values
they apply to the top, right, bottom, and left, respectively.
The style is specified as a <line-style> keyword, where
No border.
Color and width are ignored (i.e., the border has width 0).
Note this means that the initial value of border-image-width
will also resolve to zero.
hidden
Same as none,
but has different behavior in the border conflict resolution rules
for border-collapsed tables [CSS2].
dotted
A series of round dots.
dashed
A series of square-ended dashes.
solid
A single line segment.
double
Two parallel solid lines with some space between them.
(The thickness of the lines is not specified,
but the sum of the lines and the space must equal border-width.)
groove
Looks as if it were carved in the canvas.
(This is typically achieved by creating a “shadow” from two colors
that are slightly lighter and darker than the specified border-color.)
Borders are drawn in front of the element’s background,
but behind the element’s content (in case it overlaps).
Example renderings of the predefined border styles.
Note: Border colors close to black or white
may need different color calculations than colors in between
in order to create the required “3D” effect
of groove, ridge, inset, or outset.
Note: There is no control over
the spacing of the dots and dashes,
nor over the length of the dashes.
Implementations are encouraged to choose a spacing
that makes the corners symmetrical.
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.
You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.
