Overview.bs

<pre class='metadata'>
Title: CSS Backgrounds and Borders Module Level 3
Status: CR
Date: 2020-12-22
Deadline: 2021-02-22
Prepare for TR: yes
Implementation Report: https://test.csswg.org/harness/results/css-backgrounds-3_dev/grouped/
Work Status: Testing
Shortname: css-backgrounds
Level: 3
Group: csswg
ED: https://drafts.csswg.org/css-backgrounds/
TR: https://www.w3.org/TR/css-backgrounds-3/
Previous Version: https://www.w3.org/TR/2017/CR-css-backgrounds-3-20171017/
Previous version: https://www.w3.org/TR/2014/CR-css3-background-20140909/
Editor: Bert Bos, W3C, bert@w3.org, w3cid 3343
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Brad Kemper, Invited Expert, brad.kemper@gmail.com, w3cid 43245
Abstract: This draft contains the features of CSS relating to borders and backgrounds. The main extensions compared to <a href="https://www.w3.org/TR/CSS2/">level&nbsp;2</a> are borders consisting of images, boxes with multiple backgrounds, boxes with rounded corners and boxes with shadows.
Test Suite: http://test.csswg.org/suites/css3-background/nightly-unstable/
At risk: animatability of 'box-shadow'
At risk: applicability of 'border' and its longhands to [=ruby base containers=] and [=ruby annotation containers=]
Use <i> Autolinks: yes
</pre>
<pre class="link-defaults">
spec:css2; type:type; text:<uri>
spec:css2; type:property; text:display
spec:css2; type:value; text:table
spec:css2; type:value; text:inline-table
spec:css2; type:value; text:table-cell
spec:css2; type:property; text:overflow
spec:css2; type:value; text:visible
spec:css-color-3; type:property; text:color
spec:css-color-3; type:value; text:transparent
spec:selectors-3; type:selector; text: ::first-letter
spec:selectors-3; type:selector; text: ::first-line
spec:css-values-3; type:type; text:<position>
</pre>

<h2 id="introduction">Introduction</h2>

<p><em>This subsection is not normative.</em>

<p>When elements are rendered according to the
<a href="https://www.w3.org/TR/css-box-3/#box-model">CSS box model</a> [[!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.)

<div class="figure">
  <p><img src="images/box.png" alt="Diagram of a typical box, showing the
  content, padding, border and margin areas">

  <p class="caption">The various areas and edges of a typical box.
  (This diagram is explained in the CSS Box Model Module [[!CSS-BOX-3]].)
</div>

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

<p>If an element is broken into multiple boxes, 'box-decoration-break' [[CSS3-BREAK]]
defines how the borders and background are divided over the various boxes.
(An element can result in more than one box if it is broken at the
end of a line, at the end of a column or at the end of a page; and
continued in the next line, column or page.)

<p>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]].

<h3 id="placement">
Module Interactions</h3>

  <p>This module replaces and extends the background and border
  features defined in [[!CSS2]] sections 8.5 and 14.2.

  <p>All properties in this module apply to the
  <a href="https://www.w3.org/TR/CSS2/selector.html#first-letter"><code>::first-letter</code></a>
  pseudo-element. The <a href="#backgrounds">background properties</a>
  and <a href="#corners">border-radius properties</a> also apply to the
  <a href="https://www.w3.org/TR/CSS2/selector.html#first-line-pseudo"><code>::first-line</code></a>
  pseudo-element. The UA may (but is not required to) apply the
  'border-image' or 'box-shadow' properties to
  <code>::first-line</code>. The UA must not apply the
  <a href="#borders">border-color/style/width properties</a> to
  <code>::first-line</code>. [[!CSS2]]

<h3 id="values">
Value Definitions</h3>

  This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
  using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
  Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].
  Combination with other CSS modules may expand the definitions of these value types.
  For example, combining with <a href="https://www.w3.org/TR/css-images/">CSS Images</a>
  allows for using CSS gradients as 'background-image' or 'border-image' values.
  [[CSS-IMAGES-3]]

  In addition to the property-specific values listed in their definitions,
  all properties defined in this specification
  also accept the <a>CSS-wide keywords</a> as their property value.
  For readability they have not been repeated explicitly.

<h3 id=animations>Animated Values</h3>

<p><!-- <a href="http://www.w3.org/Style/CSS/Tracker/issues/210">ISSUE-210.]</a> -->
It is expected that CSS will include ways to
animate transitions between styles. (The
section <a href="https://www.w3.org/TR/css-transitions-1/#animatable-types">“Animation of property types”</a>
of the <cite>CSS Transitions
module</cite> [[CSS3-TRANSITIONS]] is expected to define how different
kinds of values are interpolated during a transition.) In anticipation
of that, this module includes a line “Animatable” for each property,
which specifies whether and how values of the property can be animated.

<h2 id="backgrounds">
Backgrounds</h2>

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

<p>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'.

<h3 id="layering">
Layering Multiple Background Images</h3>

<p>The background of a box can have multiple <span
class=index>layers</span> in CSS3. The number
of layers is determined by the number of comma-separated values in the
'background-image' property. Note that a value of ''background-image/none'' still creates
a layer.

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

<div class="example">
<p>For example, this set of declarations:
<pre>
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;
</pre>
<p>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):
<pre>
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<strong>, border-box</strong>;
background-repeat: no-repeat<strong>, no-repeat, no-repeat</strong>;
</pre>
</div>

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

<p class="note">Note that the <a href="#border-images">border-image properties</a>
can also define a background image, which, if present, is painted on top of
the background created by the background properties.

<h3 id="background-color" oldids="the-background-color">Base Color: the 'background-color' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>background-color</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<color>>
    <tr>
      <th>Initial:
      <td>transparent
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>N/A
    <tr>
      <th>Computed value:
      <td>computed color
    <tr>
      <th>Animation type:
      <td>by computed value
</table>

<p>This property sets the <span class=index
title="color!!background">background color</span> of an element. The
color is drawn behind any background images.

<div class="example">
<p>Example:
<pre>h1 { background-color: #F00 } /* Sets background to red. */</pre>
</div>

<p>The background color is clipped according to the 'background-clip'
value associated with the bottom-most background image layer.

<h3 id="background-image" oldids="the-background-image">Image Sources: the 'background-image' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>background-image</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<bg-image>>#
    <tr>
      <th>Initial:
      <td>none
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>N/A
    <tr>
      <th>Computed value:
      <td>computed <<image>>
    <tr>
      <th>Animation type:
      <td>discrete
</table>

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

<pre class=prod><dfn><<bg-image>></dfn> = <<image>> | none</pre>

<p>A value of <dfn value for="background-image">none</dfn>
counts as an image layer but draws
nothing. An image that is empty (zero width or zero height), that
fails to download, or that cannot be displayed (e.g., because it is
not in a supported image format) likewise counts as a layer but
draws nothing.

<p>See the section <a href="#layering">“Layering multiple background
images”</a> for how 'background-image' interacts with other
comma-separated background properties to form each background image
layer.

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

<p>For accessibility reasons, authors should not use background images
as the sole method of conveying important information.
See <a href="https://www.w3.org/TR/2008/NOTE-WCAG20-TECHS-20081211/F3">Web
Content Accessibility Guideline F3</a> [[WCAG20]]. Images are not
accessible in non-graphical presentations, and background images
specifically might be turned off in high-contrast display modes.

<p class="note">Note that stylistic foreground images can be provided
in CSS with the
<a href="https://www.w3.org/TR/CSS2/generate.html#content">content</a>
property. (Semantically-important foreground images should be provided
in the document markup, e.g. with the &lt;img&gt; tag in HTML.)</p>

<p class="note"><a href="https://www.w3.org/TR/media-frags/#naming-space">Media fragments</a>
can be used to display a portion of an image. The
<a href="https://www.w3.org/TR/css3-images/">CSS Images</a> module
will provide fallback syntax for image formats and include additional
controls for image display.

<div class="example">
<p>Some examples specifying background images:</p>
<pre>
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); }
</pre>
</div>

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



<h3 id="background-repeat" oldids="the-background-repeat">Tiling Images: the 'background-repeat' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>background-repeat</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<repeat-style>>#
    <tr>
      <th>Initial:
      <td>repeat
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>N/A
    <tr>
      <th>Computed value:
      <td>list, each item a pair of keywords, one per dimension
    <tr>
      <th>Animation type:
      <td>discrete
</table>

<p>Specifies how background images are tiled after they have been
<a href="#the-background-size">sized</a> and <a href="#the-background-position">positioned</a>.
Where
<pre class=prod><dfn><<repeat-style>></dfn> = repeat-x | repeat-y | [repeat | space | round | no-repeat]{1,2}</pre>

<p>Single values for <<repeat-style>> have the following
meanings:

<dl dfn-type=value dfn-for=background-repeat>
  <dt><dfn>repeat-x</dfn>
  <dd>
  Computes to ''repeat no-repeat''.

  <dt><dfn>repeat-y</dfn>
  <dd>
  Computes to ''no-repeat repeat''.

  <dt>''background-repeat/repeat''
  <dd>
  Computes to ''repeat repeat''.

  <dt>''background-repeat/space''
  <dd>
  Computes to ''space space''

  <dt>''background-repeat/round''
  <dd>
  Computes to ''round round''

  <dt>''no-repeat''
  <dd>
  Computes to ''no-repeat no-repeat''
</dl>

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

<dl dfn-for=background-repeat dfn-type=value>
  <dt><dfn>repeat</dfn>
  <dd>
  The image is repeated in this direction as often as needed to cover
  the <span class=index>background painting area</span>.

  <dt><dfn>space</dfn>
  <dd>
  The image is repeated as often as will fit within the
  <span class=index>background positioning area</span> 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 <span
  class=index>background
  painting area</span> is larger than the background positioning area, then
  the pattern repeats to fill the background painting area.
  The value of 'background-position' for this direction
  is ignored, unless there is not enough space for two copies of the
  image in this direction, in which case only one image is placed and
  'background-position' determines its position in this
  direction.

  <dt><dfn>round</dfn>
  <dd>
  The image is repeated as often as will fit within the
  <span class=index>background positioning area.</span> 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 <span
  class=index>background
  painting area</span> is larger than the background positioning area, then
  the pattern repeats to fill the background painting area.

  <dt><dfn>no-repeat</dfn>
  <dd>
  The image is placed once and not repeated in this direction.
</dl>

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

<div class="example">
<p style="display:none">Example(s):
<pre>
body {
  background: white url("pendant.png");
  background-repeat: repeat-y;
  background-position: center;
}
</pre>

<div class="figure">
  <p><img src="images/bg-repeat.png" alt="A centered background image, with
  copies repeated up and down the border, padding and content
  areas."><!--<SPAN class="dlink">&nbsp;&nbsp;&nbsp;<A
  name="img-bg-repeat" href="images/longdesc/bg-repeat-desc.html"
  title="Long description for background pattern">[D]</A></SPAN>-->

  <p class="caption">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.
</div>
</div>

<div class=example>
  <p style="display:none">Example(s):
  <pre>
body {
  background-image: url(dot.png) white;
  background-repeat: space
}
</pre>

  <div class=figure>
    <p><img src="images/bg-space.png" alt="Image of an element with a dotted background">

    <p class=caption>The effect of ''background-repeat/space'': the image of a dot is
    tiled to cover the whole background and the images are equally
    spaced.
  </div>
</div>

<p>See the section <a href="#layering">“Layering multiple background
images”</a> for how 'background-repeat' interacts with other
comma-separated background properties to form each background image
layer.



<h3 id="background-attachment" oldids="the-background-attachment">Affixing Images: the 'background-attachment' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>background-attachment</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<attachment>>#
    <tr>
      <th>Initial:
      <td>scroll
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>N/A
    <tr>
      <th>Computed value:
      <td>list, each item the keyword as specified
    <tr>
      <th>Animation type:
      <td>discrete
</table>

<p>If background images are specified, this property specifies whether
they are fixed with regard to the <em class="index">viewport</em>
(''fixed'') or scroll along with the element (''scroll'')
or its contents (''local''). The property's value is given as
a comma-separated list of &lt;attachment&gt; keywords where

<pre class=prod><dfn><<attachment>></dfn> = scroll | fixed | local</pre>

<dl dfn-for=background-attachment dfn-type=value>
  <dt><dfn>fixed</dfn></dt>
    <dd>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 <a href="https://www.w3.org/TR/CSS2/page.html#page-box">page box</a>
      and therefore replicated on every page.
      <span class="note">Note that there is only one viewport per view.
      Even if an element has a scrolling mechanism (see  the 'overflow'
      property [[!CSS2]]), a ''fixed'' background doesn't move with the
      element.</span>
  <dt><dfn>local</dfn></dt>
    <dd>The background is fixed with regard to the element's contents:
      if the element has a scrolling mechanism,
      the background scrolls with the element's contents,
      and the <i>background painting area</i> and <i>background positioning area</i>
      are relative to the scrollable area of the element rather than to the border framing them.
      Because the scrollable area does not include the border area,
      for scrollable elements the ''background-clip/border-box'' value of 'background-clip'
      may be treated the same as ''background-clip/padding-box''.</dd>
  <dt><dfn>scroll</dfn></dt>
    <dd>The background is fixed with regard to the element itself and
      does not scroll with its contents. (It is effectively attached
      to the element's border.)</dd>
</dl>

<p>Even if the image is fixed, it is still only visible when it is in
the <em class=index>background painting area</em> of the element or otherwise
unclipped. (See <a href="#special-backgrounds"> “The backgrounds of
special elements”</a> for the cases when background images are not
clipped.) Thus, unless the image is tiled, it may be invisible.

<div class="example">
<p>This example creates an infinite vertical band that remains
“glued” to the viewport when the element is scrolled.

<pre>
body {
  background: red url("pendant.gif");
  background-repeat: repeat-y;
  background-attachment: fixed;
}
</pre>
</div>

<p>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:

<pre class=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;
}
</pre>

<p>See the section <a href="#layering">“Layering multiple background
images”</a> for how 'background-attachment' interacts with other
comma-separated background properties to form each background image
layer.



<h3 id="background-position" oldids="the-background-position">Positioning Images: the 'background-position' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>background-position</dfn>
    <tr>
      <th><a href="#values">Value</a>:

      <td><<bg-position>>#
    <tr>
      <th>Initial:
      <td>0% 0%
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>refer to size of <span class=index>background positioning
      area</span> <em>minus</em> size of background image; see text
    <tr>
      <th>Computed value:
      <td>list, each item
        a pair of offsets (horizontal and vertical) from the top left origin
        each given as a computed <<length-percentage>> value
    <tr>
      <th>Animation type:
      <td>repeatable list
</table>

<p>If background images have been specified, this property specifies
their initial position (after any <a href="#the-background-size">resizing</a>)
within their corresponding <span>background positioning area.</span>

<p>Where
<pre class=prod><dfn><<bg-position>></dfn> =
  [ left | center | right | top | bottom | <<length-percentage>> ]
|
  [ left | center | right | <<length-percentage>> ]
  [ top | center | bottom | <<length-percentage>> ]
|
  [ center | [ left | right ] <<length-percentage>>? ] &amp;&amp;
  [ center | [ top | bottom ] <<length-percentage>>? ]
</pre>

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

<p class="note">Note that 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.

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

<p>Positive values represent an offset <em>inward</em> from the edge of
the background positioning area. Negative values represent an offset
<em>outward</em> from the edge of the background positioning area.

<div class="example">
  <p>The following declarations give the stated (horizontal, vertical)
    offsets from the top left corner:</p>
  <pre>
 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 */</pre>
</div>

<dl dfn-for=background-position dfn-type=value>
  <dt><dfn><<percentage>></dfn>

  <dd><p>A percentage for the horizontal offset is relative to (<var>width of
    background positioning area</var> - <var>width of background image</var>).
    A percentage for the vertical offset is relative to (<var>height
    of background
    positioning area</var> - <var>height of background image</var>), where the
    size of the image is the size given by 'background-size'.
    <div class=example>
      <p>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.
      <div class="figure">
      <p><img alt="Diagram of image position within element" src="images/bg-pos.png">
      <p class="caption">Diagram of the meaning of ''background-position: 75% 50%''.
      </div>
    </div>

  <dt><dfn><<length>></dfn>

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

  <dt><dfn>''top''</dfn>

  <dd>Computes to ''0%'' for the vertical position if one or two
    values are given, otherwise specifies the top edge as the origin for the
    next offset.

  <dt><dfn>''right''</dfn>

  <dd>Computes to ''100%'' for the horizontal position if one or two
    values are given, otherwise specifies the right edge as the origin
    for the next offset.

  <dt><dfn>''bottom''</dfn>

  <dd>Computes to ''100%'' for the vertical position if one or two
    values are given, otherwise specifies the bottom edge as the origin
    for the next offset.

  <dt><dfn>''left''</dfn>

  <dd>Computes to ''0%'' for the horizontal position if one or two
    values are given, otherwise specifies the left edge as the origin
    for the next offset.

  <dt><dfn>''center''</dfn>

  <dd>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.
</dl>

<div class="example">
  <p>The following 'background' shorthand declarations use keywords
  to set 'background-position' to the stated percentage values.</p>
  <pre>
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% */
</pre>
</div>

<div class="example">
  <p>In the example below, the (single) image is placed in the lower-right
  corner of the viewport.
  <pre>
body {
  background-image: url("logo.png");
  background-attachment: fixed;
  background-position: 100% 100%;
  background-repeat: no-repeat;
}
</pre>
</div>

<div class=example>
<p>Background positions can also be relative to other corners than the
top left. E.g., the following puts the background image 10px from the
bottom and 3em from the right:

<pre>background-position: right 3em bottom 10px</pre>
</div>

<p>See the section <a href="#layering">“Layering multiple background
images”</a> for how 'background-position' interacts with
other comma-separated background properties to form each background
image layer.



<h3 id="background-clip" oldids="the-background-clip">Painting Area: the 'background-clip' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>background-clip</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<box>>#
    <tr>
      <th>Initial:
      <td>border-box
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>N/A
    <tr>
      <th>Computed value:
      <td>list, each item a keyword as specified
    <tr>
      <th>Animation type:
      <td>repeatable list
</table>

<p>Determines the <dfn id="background-painting-area">background painting area</dfn>,
which determines the area within which the background is painted.
The syntax of the property is given with

<pre class=prod><dfn><<box>></dfn> = border-box | padding-box | content-box</pre>

<p>Values have the following meanings:

<dl dfn-for=background-clip dfn-type=value>
  <dt><dfn>border-box</dfn></dt>
  <dd>The background is painted within (clipped to) the
    <span>border box.</span>
  <dt><dfn>padding-box</dfn></dt>
  <dd>The background is painted within (clipped to) the
    <span>padding box.</span>
  <dt><dfn>content-box</dfn></dt>
  <dd>The background is painted within (clipped to) the
    <span>content box.</span>
</dl>

<p class=note>Note that the root element has a different <span>background
painting area,</span> and thus the 'background-clip' property has no effect
when specified on it. See <a href="#special-backgrounds"> “The
backgrounds of special elements.”</a>

<p class=note>Note that the background is always drawn <em>behind</em>
the border, if any. See “Elaborate description of Stacking Contexts” in
[[!CSS2]].

<p>See the section on <a href="#corner-shaping">Corner Shaping</a>
for how 'border-radius' affects the shape of the <i>background painting area</i>.

<p>See the section <a href="#layering">“Layering multiple background
images”</a> for how ''background-clip'' interacts with other
comma-separated background properties to form each background image
layer.



<h3 id="background-origin" oldids="the-background-origin">Positioning Area: the 'background-origin' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>background-origin</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<box>>#
    <tr>
      <th>Initial:
      <td>padding-box
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>N/A
    <tr>
      <th>Computed value:
      <td>list, each item a keyword as specified
    <tr>
      <th>Animation type:
      <td>repeatable list
</table>

<p>For elements rendered as a single box, specifies the
<dfn id="background-positioning-area">background positioning area</dfn>.
For elements rendered as multiple boxes
(e.g., inline boxes on several lines, boxes on several pages),
specifies which boxes 'box-decoration-break' [[CSS3-BREAK]] operates on
to determine the background positioning area(s).

<dl dfn-for=background-origin dfn-type=value>
  <dt><dfn>padding-box</dfn>
  <dd>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.)
  <dt><dfn>border-box</dfn>
  <dd>The position is relative to the border box.
  <dt><dfn>content-box</dfn>
  <dd>The position is relative to the content box.
</dl>

<p>If the 'background-attachment' value for this image is
''fixed'', then this property has no effect: in this case the
background positioning area is the
<a href="https://www.w3.org/TR/CSS2/visudet.html#containing-block-details">initial containing block</a> [[!CSS2]].

<p class="note">Note that if 'background-clip' is ''background-clip/padding-box'',
'background-origin' is ''background-origin/border-box'', 'background-position' is
''top left'' (the initial value), and the element has a
non-zero border, then the top and left of the background image will be
clipped.

<p>See the section <a href="#layering">“Layering multiple background
images”</a> for how ''background-origin'' interacts with other
comma-separated background properties to form each background image
layer.



<h3 id="background-size" oldids="the-background-size">Sizing Images: the 'background-size' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>background-size</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<bg-size>>#
    <tr>
      <th>Initial:
      <td>auto
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>see text
    <tr>
      <th>Computed value:
      <td>list, each item a pair of sizes (one per axis)
      each represented as either a keyword or a computed <<length-percentage>> value
    <tr>
      <th>Animation type:
      <td>repeatable list
</table>

<p>Specifies the size of the background images. Where

<pre class=prod><dfn><<bg-size>></dfn> = [ <<length-percentage [0,&infin;]>> | auto ]{1,2} | cover | contain</pre>

<p>Values have the following meanings:

<dl dfn-for=background-size dfn-type=value>
  <dt><dfn>contain</dfn></dt>
  <dd>Scale the image, while preserving its [=natural aspect ratio=]
    (if any), to the largest size such that both its width and its
    height can fit inside the <span class=index>background
    positioning area.</span></dd>

  <dt><dfn>cover</dfn></dt>
  <dd>Scale the image, while preserving its [=natural aspect ratio=]
    (if any), to the smallest size such that both its width and its
    height can completely cover the background positioning area.</dd>

  <dt>[ <dfn><<length-percentage [0,&infin;]>></dfn>
  | <dfn>auto</dfn> ]{1,2}</dt>
  <dd>
    <p>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 ''background-size/auto''.

    <p>A percentage is relative to the background positioning area.

    <p>An ''background-size/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%.

    <p>If both values are ''background-size/auto'' then the [=natural width=] and/or
    [=natural height|height=] of the image should be used, if any, the missing dimension
    (if any) behaving as ''background-size/auto'' as described above. If the image has
    neither [=natural size=], its size is
    determined as for ''contain''.

    <p>Negative values are invalid.
  </dd>
</dl>

<div class="example">
<p>Here are some examples. The first example stretches the background
image independently in both dimensions to completely cover the content
area:

<pre>
div {
    background-image: url(plasma.png);
    background-repeat: no-repeat;
    background-size: 100% 100%;
    background-origin: content-box }
</pre>

<p>The second example stretches the image so that exactly two copies
fit horizontally. The aspect ratio is preserved:

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

<p>This example forces the background image to be 15 by 15 pixels:

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

<p>This example uses the image's natural size. Note that this is the
only possible behavior in CSS level&nbsp;1 and 2.

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

<p>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. The width of the image is 20% of the background positioning area width and is
not rounded.

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

<p>If 'background-repeat' is ''background-repeat/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):

<blockquote>
  <p>If <var>X</var> &ne; 0 is the width of the image after step one
  and <var>W</var> is the width of the background positioning area,
  then the rounded width
  <var>X'</var> = <var>W</var> / round(<var>W</var> / <var>X</var>)
  where round() is a function that returns the nearest natural number
  (integer greater than zero).
</blockquote>

<p>If 'background-repeat' is ''background-repeat/round'' for one dimension only and if
'background-size' is ''background-size/auto'' for the other dimension, then there is a third
step: that other dimension is scaled so that the original aspect ratio
is restored.

<div class=example>
<p>In this example the background image is shown at its natural size:

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

<p>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:

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

<p>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:

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

<p>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:

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

<p>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 correspond to a 4em height at the original aspect ratio:
scaled slightly so that it fits a whole number of times in the background
width.

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

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

<p>See the section <a href="#layering">“Layering multiple background
images”</a> for how 'background-size' interacts with other
comma-separated background properties to form each background image
layer.

<h3 id="background" oldids="the-background">Backgrounds Shorthand: the 'background' property</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn id="background">background</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td>[<<bg-layer>># ,]? <<final-bg-layer>>
    <tr>
      <th>Initial:
      <td>see individual properties
    <tr>
      <th>Applies to:
      <td>all elements
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>see individual properties
    <tr>
      <th>Computed value:
      <td>see individual properties
    <tr>
      <th>Animation type:
      <td>see individual properties
</table>

<p>Where

<pre class=prod><dfn><<bg-layer>></dfn> = <<bg-image>> || <<bg-position>> [ / <<bg-size>> ]? || <<repeat-style>> || <<attachment>> || <<box>> || <<box>></pre>

<pre class=prod><dfn><<final-bg-layer>></dfn> =  <<'background-color'>> || <<bg-image>> || <<bg-position>> [ / <<bg-size>> ]? || <<repeat-style>> || <<attachment>> || <<box>> || <<box>></pre>

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

<p>The 'background' property is a
shorthand property for setting most background properties at the same
place in the style sheet. The number of comma-separated items defines
the number of background layers. Given a valid declaration, for each layer
the shorthand first sets the corresponding layer of each of
'background-image',
'background-position',
'background-size',
'background-repeat',
'background-origin',
'background-clip'
and 'background-attachment' to
that property's initial value, then assigns any explicit values specified
for this layer in the declaration. Finally 'background-color' is set to
the specified color, if any, else set to its initial value.

<p>If one <<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'.

<div class="example">
<p style="display:none">Examples:

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

<pre>
body { background: red }
p { background: url("chess.png") 40% / 10em gray
       round fixed border-box; }
</pre>

<p>The first rule is equivalent to:

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

<p>The second is equivalent to:

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

<div class=example>
<p>The following example shows how a both a background color (<span
class=css>#CCC</span>) and a background image (<span
class=css>url(metal.jpg)</span>) are set. The image is rescaled to
the full width of the element:

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

<div class=example>
<p>Another example shows equivalence:

<pre>
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 }
</pre>
</div>

<div class=example>
<p>The following declaration with multiple, comma-separated values

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

<p>is equivalent to

<pre>
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;
</pre>
</div>


<h3 id="special-backgrounds">
Backgrounds of Special Elements</h3>

<p>The document <a href="https://www.w3.org/TR/CSS2/intro.html#the-canvas">canvas</a>
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 &lt;body&gt; element)
as described below.
However, the element whose background would be used for the canvas
is ''display: none'',
then the [=canvas background=] is transparent.

<p>If the [=canvas background=] is not opaque,
the <dfn export>canvas surface</dfn> below it shows through.
The texture of the [=canvas surface=] is UA-dependent
(but is typically an opaque white).

<h4 id="root-background">
The Canvas Background and the Root Element</h4>

<p>The background of the root element becomes the <dfn export>canvas background</dfn>
and its <span class=index>background painting area</span> extends
to cover the entire <a href="https://www.w3.org/TR/CSS2/intro.html#the-canvas">canvas</a>.
However, any images are sized and positioned relative to the root element
as if they were painted for that element alone.
(In other words, the
<a href="#background-positioning-area">background <em>positioning</em> area</a>
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.

<h4 id="body-background">
The Canvas Background and the HTML &lt;body&gt; Element</h4>

<p>For documents whose root element is
an HTML <code class="html">HTML</code> element
or an XHTML <code class="html">html</code> element [[!HTML]]:
if the computed
value of 'background-image' on the root element is ''background-image/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 <code class="html">BODY</code> or XHTML <code class="html">body</code>
child element. The used values of that <code class="html">BODY</code> element's
background properties are their initial values, and the propagated values
are treated as if they were specified on the root element.
It is recommended that authors of HTML documents specify the canvas background
for the <code class=html>BODY</code> element rather than the
<code class=html>HTML</code> element.

<div class="example">
<p>According to these rules, the canvas underlying the following HTML
document will have a “marble” background:

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

<h4 id="first-line-background">
The ''::first-line'' Pseudo-element‘s Background</h4>

<p>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 margin.

<h2 id="borders">
Borders</h2>

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

<h3 id="border-color" oldids="the-border-color">Line Colors: the 'border-color' properties</h3>

<table class="propdef">
  <tr>
    <th>Name:
    <td><dfn>border-top-color</dfn> ,
        <dfn>border-right-color</dfn>,
        <dfn>border-bottom-color</dfn>,
        <dfn>border-left-color</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td><<color>>
  <tr>
    <th>Initial:
    <td><a href="https://www.w3.org/TR/css-color-4/#currentcolor">currentColor</a>
  <tr>
    <th>Applies to:
    <td>all elements except [=ruby base containers=] and [=ruby annotation containers=]
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>computed color
  <tr>
    <th>Animation type:
    <td>by computed value
</table>

<table class="propdef">
  <tr>
    <th>Name:
    <td><dfn id="border-color">border-color</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td><<color>>{1,4}
  <tr>
    <th>Initial:
    <td>(see individual properties)
  <tr>
    <th>Applies to:
    <td>all elements except [=ruby base containers=] and [=ruby annotation containers=]
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>see individual properties
  <tr>
    <th>Animatable:
    <td>see individual properties
</table>

<p>These properties set the foreground color of the border specified
by the <span class=property>border-style</span> properties.

<p>The 'border-color' property is a shorthand property for setting
'border-top-color', 'border-right-color', 'border-bottom-color', and 'border-left-color'
in a single declaration.

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



<h3 id="border-style" oldids="the-border-style">Line Patterns: the 'border-style' properties</h3>

<table class="propdef">
  <tr>
    <th>Name:
    <td><dfn>border-top-style</dfn>,
        <dfn>border-right-style</dfn>,
        <dfn>border-bottom-style</dfn>,
        <dfn>border-left-style</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td><<line-style>>
  <tr>
    <th>Initial:
    <td>none
  <tr>
    <th>Applies to:
    <td>all elements except [=ruby base containers=] and [=ruby annotation containers=]
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>specified keyword
  <tr>
    <th>Animation type:
    <td>discrete
</table>

<table class="propdef">
  <tr>
    <th>Name:
    <td><dfn>border-style</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td><<line-style>>{1,4}
  <tr>
    <th>Initial:
    <td>(see individual properties)
  <tr>
    <th>Applies to:
    <td>all elements except [=ruby base containers=] and [=ruby annotation containers=]
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>see individual properties
  <tr>
    <th>Animation type:
    <td>see individual properties
</table>

<p>
  These properties control whether a border appears,
  and if it does what style it's drawn in
  (if it is not overridden by a <a href="#border-images">border image</a>).

<p>The 'border-style' property is a shorthand property for setting
'border-top-style', 'border-right-style', 'border-bottom-style', and 'border-left-style'
in a single declaration.

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

<p>Where
<pre class=prod><dfn><<line-style>></dfn> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset</pre>

<p>Values have the following meanings:

<dl dfn-type=value dfn-for="<line-style>, border-style, border-top-style, border-left-style, border-bottom-style, border-right-style, border">
  <dt><dfn>none</dfn>
  <dd>
  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.

  <dt><dfn>hidden</dfn>
  <dd>
  Same as ''border-style/none'', but has different behavior in the border conflict
  resolution rules for border-collapsed tables [[!CSS2]].

  <dt><dfn>dotted</dfn>
  <dd>
  A series of round dots.

  <dt><dfn>dashed</dfn>
  <dd>
  A series of square-ended dashes.

  <dt><dfn>solid</dfn>
  <dd>
  A single line segment.

  <dt><dfn>double</dfn>
  <dd>
  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'.)

  <dt><dfn>groove</dfn>
  <dd>
  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'.)

  <dt><dfn>ridge</dfn>
  <dd>
  Looks as if it were coming out of the canvas.

  <dt><dfn>inset</dfn>
  <dd>
  Looks as if the content on the inside of the border is sunken into the canvas.
  Treated as ''ridge'' in the
  <a href="https://www.w3.org/TR/CSS2/tables.html#collapsing-borders">collapsing border model</a>. [[!CSS2]]

  <dt><dfn>outset</dfn>
  <dd>
  Looks as if the content on the inside of the border is coming out of
  the canvas.
  Treated as ''groove'' in the
  <a href="https://www.w3.org/TR/CSS2/tables.html#collapsing-borders">collapsing border model</a>. [[!CSS2]]
</dl>

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

<div class="figure">
  <p><img alt="Examples of border styles" src="images/borderstyles.png">

  <p class=caption>Example renderings of the predefined border styles.
</div>

<p class="note">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'', ''border-style/inset'', or ''border-style/outset''.

<p class="note">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.

<p class="note">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.

<h3 id="border-width" oldids="the-border-width">Line Thickness: the 'border-width' properties</h3>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>border-top-width</dfn>, <dfn>border-right-width</dfn>,
        <dfn>border-bottom-width</dfn>, <dfn>border-left-width</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<line-width>>
    <tr>
      <th>Initial:
      <td>medium
    <tr>
      <th>Applies to:
      <td>all elements except [=ruby base containers=] and [=ruby annotation containers=]
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>N/A
    <tr>
      <th>Computed value:
      <td>absolute length; zero if the border style is ''border-style/none'' or ''hidden''
    <tr>
      <th>Animatable:
      <td>by computed value
</table>

<table class="propdef">
    <tr>
      <th>Name:
      <td><dfn>border-width</dfn>
    <tr>
      <th><a href="#values">Value</a>:
      <td><<line-width>>{1,4}
    <tr>
      <th>Initial:
      <td>(see individual properties)
    <tr>
      <th>Applies to:
      <td>all elements except [=ruby base containers=] and [=ruby annotation containers=]
    <tr>
      <th>Inherited:
      <td>no
    <tr>
      <th>Percentages:
      <td>see individual properties
    <tr>
      <th>Computed value:
      <td>see individual properties
    <tr>
      <th>Animatable:
      <td>see individual properties
</table>

<p>These properties set the thickness of the border.
Where

<pre class=prod><dfn><<line-width>></dfn> = <<length [0,&infin;]>> | thin | medium | thick</pre>

<p dfn-type=value dfn-for="<line-width>, border-width, border-top-width, border-left-width, border-bottom-width, border-right-width, border">
The lengths corresponding to <dfn>thin</dfn>, <dfn>medium</dfn>, and <dfn>thick</dfn>
are not specified, but the values are constant throughout a
<span>document</span> and thin &le; medium &le; thick. A UA could,
e.g., make the thickness depend on the ''medium'' font size: one
choice might be 1, 3 &amp; 5px when the ''medium'' font size is 17px or
less. Negative values are invalid.

<p>The 'border-width' property is a shorthand property for setting
'border-top-width', 'border-right-width', 'border-bottom-width', and 'border-left-width'
in a single declaration.

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

<p class="note">Note that the initial width is ''medium'', but the initial
style is ''border-style/none'' and therefore the used width is 0.

<h3 id="border-shorthands" oldids="the-border-shorthands">Border Shorthand Properties</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border-top</dfn>,
        <dfn>border-right</dfn>,
        <dfn>border-bottom</dfn>,
        <dfn>border-left</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td><<line-width>> ||
        <<line-style>> ||
        <<color>>
  <tr>
    <th>Initial:
    <td>See individual properties
  <tr>
    <th>Applies to:
    <td>all elements except [=ruby base containers=] and [=ruby annotation containers=]
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>see individual properties
  <tr>
    <th>Animatable:
    <td>see individual properties
</table>

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

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td><<line-width>> ||
        <<line-style>> ||
        <<color>>
  <tr>
    <th>Initial:
    <td>See individual properties
  <tr>
    <th>Applies to:
    <td>all elements except [=ruby base containers=] and [=ruby annotation containers=]
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>see individual properties
  <tr>
    <th>Animatable:
    <td>see individual properties
</table>

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

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

<div class="example">
<p>For example, the first rule below is equivalent to the set of five
rules shown after it:

<pre>
p { border: solid red }
p {
  border-top: solid red;
  border-right: solid red;
  border-bottom: solid red;
  border-left: solid red;
  border-image: none;
}
</pre>
</div>

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

<div class="example">
<p>Consider this example:
<pre>
blockquote {
  border-color: red;
  border-left: double;
  color: black
}
</pre>

<p>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.
</div>


<h2 id="corners">Rounded Corners</h2>

<h3 id="border-radius" oldids="the-border-radius">Curve Radii: the 'border-radius' properties</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td>
        <dfn>border-top-left-radius</dfn>,
        <dfn>border-top-right-radius</dfn>,
        <dfn>border-bottom-right-radius</dfn>,
        <dfn>border-bottom-left-radius</dfn>
    <tr>
    <th><a href="#values">Value</a>:
    <td><<length-percentage [0,&infin;]>>{1,2}
  <tr>
    <th>Initial:
    <td>0
  <tr>
    <th>Applies to:
    <td>all elements (but see prose)
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>Refer to corresponding dimension of the
        <a>border box</a>.
  <tr>
    <th>Computed value:
    <td>pair of computed <<length-percentage>> values
  <tr>
    <th>Animatable:
    <td>by computed value
</table>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border-radius</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td><<length-percentage [0,&infin;]>>{1,4} [ / <<length-percentage [0,&infin;]>>{1,4} ]?
  <tr>
    <th>Initial:
    <td>see individual properties
  <tr>
    <th>Applies to:
     <td>all elements (but see prose)
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>Refer to corresponding dimension of the
        <a>border box</a>.
  <tr>
    <th>Computed value:
    <td>see individual properties
  <tr>
    <th>Animatable:
    <td>see individual properties
</table>

<p>The two <<length-percentage>> values of the 'border-*-radius'
properties define the <dfn id="border-radii" lt="border radius">radii</dfn> 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, the second the vertical
radius. If the second value is omitted it is copied from the first.
If either length is zero, the corner is square, not rounded.
Percentages for the horizontal radius refer to the width of the
border box, whereas percentages for the vertical radius refer to
the height of the border box. Negative values are invalid.

<div class="figure">
  <p><img alt="Diagram of the inscribed ellipse" src="images/corner.png">

  <p class=caption>The two values of
  ''border-top-left-radius: 55pt 25pt'' define the
  curvature of the corner.
</div>

<div class=example>
<p>This example draws ovals of 15em wide and 10em high:

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

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

<div class="example">
<pre>
border-radius: 4em;
</pre>
is equivalent to
<pre>
border-top-left-radius:     4em;
border-top-right-radius:    4em;
border-bottom-right-radius: 4em;
border-bottom-left-radius:  4em;
</pre>
and
<pre>
border-radius: 2em 1em 4em / 0.5em 3em;
</pre>
is equivalent to
<pre>
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;
</pre>
</div>

<h3 id="corner-shaping">Corner Shaping</h3>

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

<p>All border styles (''solid'', ''dotted'',  ''border-style/inset'', etc.)
follow the curve of the border.

<div class="figure">
  <p><img alt="The effect of rounded corners on unequal borders"
  src="images/smooth-radius.png">

  <p class=caption>The effect of a rounded corner when the two borders
  it connects are of unequal thickness (left) and the effect of a
  rounded corner on borders that are thicker than the radius of the
  corner (right).
</div>

<p class="note">Note that if the center of a corner's outer curve is past an
opposite padding edge (in the border area of a side opposite the corner),
the inner curve will not be a full quarter ellipse.</p>

<div class="figure">
  <table>
    <tr><td><pre>p { width: 70px; height: 70px; border: solid 30px;
<!--            -->    border-color: orange orange silver silver;
<!--            -->    border-top-right-radius: 100%; }</pre>
    <td><img alt="The curved corner is an arc from the top left corner sweeping
               across the top right corner to the bottom right corner, describing
               a quarter-ellipse; but since the opposite sides have a border
               thickness the padding edge curve starts inward from the outer arc's
               endpoints."
          src="images/partial-curve.png">
  </table>
  <p class=caption>Where the border-radius curve extends into the opposite
  sides' borders, the arc of the padding edge is less than 90&deg;.
</div>

<p>The margin edge, being outside the border edge, calculates its radius
by <em>adding</em> the corresponding margin thickness to each border radius.
However, in order to create a sharper corner when the border radius is small
(and thus ensure continuity between round and sharp corners),
when the <i>border radius</i> is less than the margin,
the margin is multiplied by the proportion 1 + (<var>r</var>-1)<sup>3</sup>,
where <var>r</var> is the ratio of the border radius to the margin,
in calculating the corner radii of the margin box shape.



<h3 id="corner-clipping">Corner Clipping</h3>

<p>Although <a href="#the-border-image">border images</a> are not affected
by 'border-radius',
other effects that clip painting or event handling
to the border, padding, or content edge
must clip to their respective curves.
For example,
backgrounds clip to the curve specified by 'background-clip',
'overflow' values other than ''visible'' to the curved padding edge,
[=replaced element=] content to the curved content edge,
pointer events to the curved border edge,
etc.

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

<div class=example>
<p>This example adds appropriate padding, so that the
contents do not overflow the corners. Note that there is no border,
but the background will still have rounded corners.

<pre>
DIV {
    background: black;
    color: white;
    border-radius: 1em;
    padding: 1em }
</pre>
</div>

<h3 id="corner-transitions">Color and Style Transitions</h3>

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

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

<div class="figure">
  <p><img alt="Illustration of the transition region on curved corners"
  src="images/transition-region.png">

  <p class=caption>Given these corner shapes, color and style transitions
    must be contained within the green region. In case D the rectangle
    defined by the border radii does not include the center of the inner
    curve (which is a sharp corner), so the transition region is expanded
    to include that corner. Transitions may take up the entire transition
    region, but are not required to: For example, a gradient color transition
    between two solid border styles might take up only the region bounded
    by the tips of the outer radii and the tips of the inner radii
    (represented in case D by the dark green region).
</div>

<h3 id="corner-overlap">Overlapping Curves</h3>

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

<p>Let <var>f</var> = min(<var>L<sub>i</sub></var>/<var>S<sub>i</sub></var>),
where <var>i</var> ∈ {top, right, bottom, left},
<var>S<sub>i</sub></var> is the sum of the two corresponding radii of the
corners on side <var>i</var>, and <var>L<sub>top</sub></var> =
<var>L<sub>bottom</sub></var> = the width of the box, and
<var>L<sub>left</sub></var> = <var>L<sub>right</sub></var> = the
height of the box. If <var>f</var> &lt; 1, then all corner radii are
reduced by multiplying them by <var>f</var>.

<p class=note>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.

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

<div class=example>
<p>For example, the borders A of the <a
href="#reduced-radius">figure below</a> might be the
result of
<pre>
box-sizing: border-box;
width: 6em;
height: 2.5em;
border-radius: 0.5em 2em 0.5em 2em
</pre>
<p>The height (2.5em) is enough for the specified radii (0.5em plus
2.0em). However, if the height is only 2em,
<pre>
box-sizing: border-box;
width: 6em;
height: 2em;
border-radius: 0.5em 2em 0.5em 2em
</pre>
<p>all corners need to be reduced by a factor 0.8 to make
them fit. The used border radii thus are 0.4em (instead of 0.5em) and
1.6em (instead of 2em). See borders B in the figure.

<div class=figure id=reduced-radius>
  <p><img src="images/corner-large-mix.png" alt="[image: rectangle with two tiny
  rounded corners and two very large ones, on opposite corners]">

  <p class=caption>These rounded corner might be the result of 'width:
  6em; height: 2.5em; border-radius: 0.5em 2em 0.5em 2em' for A; and
  ditto but with 'height: 2em' for B.
</div>
</div>

<h3 id="border-radius-tables">Effect on Tables</h3>

<p>The 'border-radius' properties do apply to
''display/table'', ''inline-table'', and ''table-cell'' boxes
in separated borders mode (''border-collapse: separate'').
When 'border-collapse' is ''border-collapse/collapse'', they have no effect.

<h2 id="border-images">Border Images</h2>

<p>Authors can specify an image to be used in place of the border styles.
In this case, the border's design is taken from the sides and corners
of an image specified with 'border-image-source', whose pieces may be
sliced, scaled and stretched in various ways to fit the size of the
<a>border image area</a>. The border-image properties do not affect layout:
layout of the box, its content, and surrounding content is based on
the 'border-width' and 'border-style' properties only.

<div class=example>
<p>This example creates a top and bottom border consisting of a whole
number of orange diamonds and a left and right border of a single,
stretched diamond. The corners are diamonds of a different color. The
image to tile is as follows. Apart from the diamonds, it is
transparent:

<p><img src="images/border.png" alt="Tile for border">

<p>The image is 81 by 81 pixels and has to be divided into 9 equal
parts. The style rules could thus be as follows:

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

<p>The result, when applied to a DIV of 12 by 5em, will be similar to
this:

<p><img src="images/borderresult.png" alt="element with a diamond border">
</div>

<div class="example">
  <p>This shows a more complicated example, demonstrating how the border
  image corresponds to the fallback border-style but can also extend
  beyond the border area. The border image is a wavy green border with
  an extended corner effect:</p>
  <div class=figure>

    <p><img src="images/groovy-border-image-slice.png" alt="Diagram: The
      border image shows a wavy green border with more exaggerated
      waves towards the corners, which are capped by a disconnected
      green circle. Four cuts at 124px offsets from each side divide
      the image into 124px-wide square corners, 124px-wide but thin
      side slices, and a small center square.">

    <p class="caption">The 'border-image-source' image, with the four
    'border-image-slice' cuts at 124px dividing the image into nine parts.</p>
  </div>

  <p>The rest of the border properties then interact to lay out the
  tiles as follows:</p>

  <div class=figure>
    <p><img src="images/border-image.png" alt="Diagram: The image-less (fallback)
    rendering has a green double border. The rendering with border-image
    shows the wavy green border, with the waves getting longer as they
    reach the corners. The corner tiles render as 124px-wide squares and
    the side tiles repeat a whole number of times to fill the space in
    between. Because of the gradual corner effects, the tiles extend deep
    into the padding area. The whole border image effect is outset 31px, so
    that the troughs of the waves align just outside the padding edge.">

    <p class=caption>Diagram of all border-image properties and how they
    interact, and showing the rendering with and without the border-image
    in effect.</p>
  </div>

  <p>Here, even though the border-width is 12px, the 'border-image-width'
  property computes to 124px. The border-image area is then outset 31px
  from the border-box and into the margin area. If the border-image fails
  to load (or border images are not supported by the UA), the fallback
  rendering uses a green double border.
</div>

<div class="example" id="border-image-border-shorthand-example">
  <p>Notice that the 'border' shorthand resets 'border-image'. This makes
    it easy to turn off or reset all border effects:</p>

  <pre>
    .notebox {
      border: double orange;
      /* must set 'border' shorthand first, otherwise it erases 'border-image' */
      border-image: url("border.png") 30 round;
      /* but other 'border' properties can be set after */
      border-width: thin thick;
    }
    ...
    .sidebar .notebox {
      box-shadow: 0 0 5px gray;
      border-radius: 5px;
      border: none; /* turn off all borders */
      /* 'border' shorthand resets 'border-image' */
    }
  </pre>
</div>

<h3 id="border-image-source" oldids="the-border-image-source">Image Source: the 'border-image-source' property</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border-image-source</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td>none | <<image>>
  <tr>
    <th>Initial:
    <td>none
  <tr>
    <th>Applies to:
    <td>All elements, except internal table elements when 'border-collapse' is
    ''border-collapse/collapse''
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>the keyword ''border-image-source/none'' or the computed <<image>>
  <tr>
    <th>Animation type:
    <td>discrete
</table>

<p>Specifies an image to use in place of the rendering specified by the 'border-style' properties
and, if given the ''fill'' keyword in 'border-image-slice', as an additional image backdrop for the element.
If the value is ''border-image-source/none'' or if the image cannot be displayed
(or the property doesn't apply), the border styles will be used;
otherwise the element's 'border-style' borders are not drawn
and the border image is drawn as described in the sections below.

<h3 id="border-image-slice" oldids="the-border-image-slice">Image Slicing: the 'border-image-slice' property</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border-image-slice</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td>[<<number [0,&infin;]>> | <<percentage [0,&infin;]>>]{1,4} &amp;&amp; fill?
  <tr>
    <th>Initial:
    <td>100%
  <tr>
    <th>Applies to:
    <td>All elements, except internal table elements when 'border-collapse' is
    ''border-collapse/collapse''
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>refer to size of the border image
  <tr>
    <th>Computed value:
    <td>four values, each either a number or percentage; plus a ''fill'' keyword if specified
  <tr>
    <th>Animation type:
    <td>by computed value
</table>

<p>This property specifies inward offsets from the top, right, bottom,
and left edges of the image, dividing it into nine regions: four corners,
four edges and a middle.
The middle image part is discarded (treated as fully transparent)
unless the ''fill'' keyword is present. (It is drawn over the background;
see <a href="#border-image-process">Drawing the Border Image</a>.)

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

<dl dfn-for=border-image-slice dfn-type=value>
  <dt><dfn><<percentage [0,&infin;]>></dfn>
  <dd>Percentages are relative to the size of the image: the width
    of the image for the horizontal offsets, the height for vertical
    offsets.

  <dt><dfn><<number [0,&infin;]>></dfn>
  <dd>Numbers represent pixels in the image (if the image is a raster
    image) or vector coordinates (if the image is a vector image).

  <dt><dfn id="border-image-slice-fill">fill</dfn>
  <dd>The ''fill'' keyword, if present, causes the middle part of
    the border-image to be preserved. (By default it is discarded,
    i.e., treated as empty.)
</dl>

<p>Negative values are invalid.
Computed values larger than the size of the image are interpreted as ''100%''.

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

<p>If the image must be sized to determine the slices
(for example, for SVG images with no [=natural dimensions=]),
then it is sized using the <a href="https://www.w3.org/TR/css3-images/#default-sizing">default sizing algorithm</a>
with no <i>specified size</i> and the <i>border image area</i> as the <i>default object size</i>.

<div class=figure>
  <p><img src="images/slice.png" alt="Diagram: two horizontal cuts and two
  vertical cuts through an image">

  <p class=caption>Diagram illustrating the cuts corresponding to the
  value ''25% 30% 12% 20%''
</div>

<h3 id="border-image-width" oldids="the-border-image-width">Drawing Areas: the 'border-image-width' property</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border-image-width</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td>[ <<length-percentage [0,&infin;]>> | <<number [0,&infin;]>> | auto ]{1,4}
  <tr>
    <th>Initial:
    <td>1
  <tr>
    <th>Applies to:
    <td>All elements, except internal table elements when 'border-collapse' is
    ''border-collapse/collapse''
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>Relative to width/height of the <a>border image area</a>
  <tr>
    <th>Computed value:
    <td>four values, each either a number, the keyword ''border-image-width/auto'', or a computed <<length-percentage>> value
  <tr>
    <th>Animation type:
    <td>by computed value
</table>

<p>The border image is drawn inside an area called the
<dfn>border image area</dfn>. This is an area whose boundaries
by default correspond to the border box, see 'border-image-outset'.

<p>The four values of 'border-image-width' specify offsets that are used
to divide the border image area into nine parts. They represent inward
distances from the top, right, bottom, and left sides of the
area, respectively.

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

Values have the following meanings:</p>

<dl dfn-for=border-image-width dfn-type=value>
  <dt><dfn><<length-percentage [0,&infin;]>></dfn>
  <dd>Percentages refer to the size of the border image area: the width of the
    area for horizontal offsets, the height for vertical offsets.

  <dt><dfn><<number [0,&infin;]>></dfn>
  <dd>Numbers represent multiples of the corresponding computed
    <a href="#the-border-width">border-width</a>.

  <dt><dfn>auto</dfn>
  <dd>If ''border-image-width/auto'' is specified then the border image width is the
    [=natural size|natural=] width or height (whichever is applicable) of the
    corresponding image slice (see 'border-image-slice'). If the image
    does not have the required [=natural dimension=] then the
    corresponding computed <a href="#the-border-width">border-width</a> is used
    instead.
</dl>

<p>Negative values are invalid for any 'border-image-width' values.

<p>If two opposite 'border-image-width' offsets are large enough that
they overlap, then the used values of all 'border-image-width' offsets
are proportionally reduced until they no longer overlap. In mathematical
notation: Given <var>L<sub>width</sub></var> as the width of the border
image area, <var>L<sub>height</sub></var> as its height, and
<var>W<sub><var>side</var></sub></var> as the border image width offset
for the <var>side</var> side, let <var>f</var> =
min(<var>L<sub>width</sub></var>/(<var>W<sub>left</sub></var>+<var>W<sub>right</sub></var>),
<var>L<sub>height</sub></var>/(<var>W<sub>top</sub></var>+<var>W<sub>bottom</sub></var>)).
If <var>f</var> &lt; 1, then all <var>W</var> are reduced by multiplying
them by <var>f</var>.

<h3 id="border-image-outset" oldids="the-border-image-outset">Edge Overhang: the 'border-image-outset' property</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border-image-outset</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td>[ <<length [0,&infin;]>> | <<number [0,&infin;]>> ]{1,4}
  <tr>
    <th>Initial:
    <td>0
  <tr>
    <th>Applies to:
    <td>All elements, except internal table elements when 'border-collapse' is
    ''border-collapse/collapse''
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>four values, each a number or absolute length
  <tr>
    <th>Animation type:
    <td>by computed value
</table>


<p>The values specify the amount by which the <a>border image area</a> extends beyond the border box.

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.

<dl dfn-for=border-image-outset dfn-type=value>
  <dt><<length [0,&infin;]>>
  <dd>Represents an outset of the specified length.

  <dt><<number [0,&infin;]>>
  <dd>Represents an outset of the specified multiple of the corresponding computed <a href="#the-border-width">border-width</a>.
</dl>

<p>Negative values are invalid.

<p>Portions of the border-image that are rendered outside the border
box do not trigger scrolling. Also such portions are invisible to mouse
events and do not capture such events on behalf of the element.</p>

<p class=note>Note that, even though they never cause a scrolling
mechanism, outset images may still be clipped by an ancestor or by the
viewport.

<h3 id="border-image-repeat" oldids="the-border-image-repeat">Image Tiling: the 'border-image-repeat' property</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border-image-repeat</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td>[ stretch | repeat | round | space ]{1,2}
  <tr>
    <th>Initial:
    <td>stretch
  <tr>
    <th>Applies to:
    <td>All elements, except internal table elements when 'border-collapse' is
    ''border-collapse/collapse''
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>two keywords, one per axis
  <tr>
    <th>Animation type:
    <td>discrete
</table>

<p>This property specifies how the images for the sides and the middle
part of the border image are scaled and tiled.
The first keyword applies to the horizontal scaling and tiling
of the top, middle and bottom parts,
the second to the vertical scaling and tiling
of the left, middle and right parts;
see <a href="#border-image-process">Drawing the Border Image</a>.
If the second keyword is absent, it is assumed to be the same as the first.
Values have the following meanings:

<dl dfn-for=border-image-repeat dfn-type=value>
  <dt><dfn>stretch</dfn></dt>
  <dd>The image is stretched to fill the area.
  <dt><dfn>repeat</dfn></dt>
  <dd>The image is tiled (repeated) to fill the area.
  <dt><dfn>round</dfn></dt>
  <dd>The image is tiled (repeated) to fill the area. If it does not
    fill the area with a whole number of tiles, the image is rescaled
    so that it does.
  <dt><dfn>space</dfn></dt>
  <dd>The image is tiled (repeated) to fill the area. If it does not
    fill the area with a whole number of tiles, the extra space is
    distributed around the tiles.
</dl>

<p>The exact process for scaling and tiling the border-image parts is
given in the section below.</p>

<h3 id="border-image-process">
Drawing the Border Image</h3>

<p>After the border-image given by 'border-image-source' is sliced by
the 'border-image-slice' values, the resulting nine images are scaled,
positioned, and tiled into their corresponding border image regions
in four steps:

<ol>
<li>Scale to 'border-image-width'.
  <ul>
  <li><p>The two images for the top and bottom edges are made as tall
  as the top and bottom <a>border image area</a> parts, respectively, and
  their width is scaled proportionally.

  <li><p>The images for the left and right edge are made as wide as the
  left and right <a>border image area</a> parts, respectively, and their
  height is scaled proportionally.

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

  <li><p>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.</p>
  </ul>

<li>Scale to 'border-image-repeat'.
  <ul>
  <li><p>If the first keyword is ''border-image-repeat/stretch'', the top, middle and bottom
  images are further scaled to be as wide as the middle part of the
  <a>border image area</a>. The height is not changed any further.

  <li><p>If the first keyword is ''border-image-repeat/round'', the top, middle and bottom
  images are resized in width, so that exactly a whole number of them
  fit in the middle part of the border-image area, exactly as for
  ''background-repeat/round'' in the 'background-repeat' property.

  <li><p>If the first keyword is ''border-image-repeat/repeat'' or ''border-image-repeat/space'', the top, middle,
    and bottom images are not changed any further.

  <li><p>The effects of ''border-image-repeat/stretch'', ''border-image-repeat/round'', ''border-image-repeat/repeat'', and ''border-image-repeat/space''
    for the second keyword are analogous, acting on the height of the left,
    middle and right images.
  </ul>

<li>Position the first tile.
  <ul>
  <li><p>If the first keyword is ''border-image-repeat/repeat'', the top, middle, and bottom
    images are centered horizontally in their respective areas. Otherwise
    the images are placed at the left edge of their respective parts
    of the border-image area.
  <li><p>If the second keyword is ''border-image-repeat/repeat'', the left, middle, and right
    images are centered vertically in their respective areas. Otherwise
    the images are placed at the top edge of their respective parts
    of the border-image area.
  </ul>

<li>Tile and draw.
  <ul>
  <li><p>The images are then tiled to fill their respective areas.
  <li><p>In the case of ''border-image-repeat/space'', any partial tiles are discarded and
    the extra space distributed before, after, and between the tiles.
    (I.e. the gap before the first tile, the gap after the last tile,
    and the gaps between tiles are equalized.)
    <span class="note">This can result in empty border-image side areas.</span>
  <li><p>The images are drawn at the same stacking level as normal borders:
    immediately in front of the background layers.
  <li><p>The middle image is not drawn unless ''fill'' was specified for 'border-image-source'.
  </ul>
</ol>

<h3 id="border-image" oldids="the-border-image">Border Image Shorthand: the 'border-image' property</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>border-image</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td>   <<'border-image-source'>>
        || <<'border-image-slice'>>
           [ / <<'border-image-width'>> |
             / <<'border-image-width'>>? / <<'border-image-outset'>> ]?
        || <<'border-image-repeat'>>
  <tr>
    <th>Initial:
    <td>See individual properties
  <tr>
    <th>Applies to:
    <td>See individual properties
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>See individual properties
  <tr>
    <th>Animatable:
    <td>See individual properties
</table>

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

<h3 id=border-image-tables>Effect on Tables</h3>

<p>The 'border-image' properties apply to the border of tables and
inline tables that have 'border-collapse' set to
''border-collapse/collapse''. However, this specification does not define how such an
image border is rendered. In particular, it does not define how the
image border interacts with the borders of cells, rows and row groups
at the edges of the table
(see <a href="https://www.w3.org/TR/2011/REC-CSS2-20110607/tables.html#border-conflict-resolution">border conflict resolution</a> in [[!CSS2]]).

<p>It is expected that a future specification will define the
rendering. It is recommended that UAs do not apply border images to
tables with collapsed borders until then.

<h2 id="misc">Miscellaneous Effects</h2>

<p class=note>
The 'box-decoration-break' property,
which defines how backgrounds and borders apply to a fragmented box,
has been moved to the <a href="https://www.w3.org/TR/css3-break/">CSS Fragmentation Module</a>. [[CSS3-BREAK]]

<h3 id="box-shadow" oldids="the-box-shadow">Drop Shadows: the 'box-shadow' property</h3>

<table class=propdef>
  <tr>
    <th>Name:
    <td><dfn>box-shadow</dfn>
  <tr>
    <th><a href="#values">Value</a>:
    <td>none | <<shadow>>#
  <tr>
    <th>Initial:
    <td>none
  <tr>
    <th>Applies to:
    <td>all elements
  <tr>
    <th>Inherited:
    <td>no
  <tr>
    <th>Percentages:
    <td>N/A
  <tr>
    <th>Computed value:
    <td>either the keyword ''box-shadow/none'' or
    a list, each item consisting of four absolute lengths
    plus a computed color and optionally also a ''box-shadow/inset'' keyword
  <tr>
    <th>Animation type:
    <td>by computed value,
    treating ''box-shadow/none'' as a zero-item list
    and appending blank shadows (''transparent 0 0 0 0'')
    with a corresponding ''box-shadow/inset'' keyword as needed
    to match the longer list
    if the shorter list is otherwise compatible with the longer one
</table>

  <p>The 'box-shadow' property attaches one or more drop-shadows to the box.
  The property accepts either
  the <dfn value for=box-shadow id="box-shadow-none">none</dfn> value, which indicates no shadows,
  or a comma-separated list of shadows, ordered front to back.

  <p>Each shadow is given as a <<shadow>>,
  represented by 2-4 length values, an optional color, and an optional ''box-shadow/inset'' keyword.
  Omitted lengths are 0; omitted colors default to the value of the 'color' property.
  <pre class=prod>
  <dfn><<shadow>></dfn> = <<color>>? &amp;&amp; [<<length>>{2} <<length [0,&infin;]>>? <<length>>?] &amp;&amp; inset?</pre>

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

  <dl>
    <dt><dfn id="shadow-offset-x">1st <<length>></dfn>
    <dd>
      Specifies the <dfn>horizontal offset</dfn> of the shadow.
      A positive value draws a shadow that is offset to the right of the box,
      a negative length to the left.

    <dt><dfn id="shadow-offset-y">2nd <<length>></dfn>
    <dd>
      Specifies the <dfn>vertical offset</dfn> of the shadow.
      A positive value offsets the shadow down, a negative one up.

    <dt><dfn id="shadow-blur-radius">3rd <<length [0,&infin;]>></dfn>
    <dd>Specifies the <dfn>blur radius</dfn>.
      Negative values are invalid.
      If the blur value is zero, the shadow’s edge is sharp.
      Otherwise, the larger the value, the more the shadow’s edge is blurred.
      See <a href="#shadow-blur">Shadow Blurring</a>, below.

    <dt><dfn id="shadow-spread-distance">4th <<length>></dfn>
    <dd>Specifies the <dfn>spread distance</dfn>.
      Positive values cause the shadow to expand in all directions by the specified radius.
      Negative values cause the shadow to contract.
      See <a href="#shadow-shape">Shadow Shape</a>, below.
      <p class="note">Note that for inner shadows,
      expanding the shadow (creating more shadow area)
      means contracting the shadow’s perimeter shape.

    <dt><dfn value for=box-shadow id="shadow-color"><<color>></dfn>
    <dd>
      Specifies the color of the shadow.
      If the color is absent, it defaults to ''currentColor''.

    <dt><dfn value for=box-shadow id="shadow-inset">inset</dfn>
    <dd>If present, the ''box-shadow/inset'' keyword changes the drop shadow
    from an <dfn local-lt="outer shadow">outer box-shadow</dfn>
      (one that shadows the box onto the canvas, as if it were lifted above the canvas)
    to an <dfn local-lt="inner shadow">inner box-shadow</dfn>
      (one that shadows the canvas onto the box, as if the box were cut out of the canvas and shifted behind it).
  </dl>

  <div class="example">
    <p>The example below demonstrates the effects of spread and blur on the shadow:
    <pre>
<!-- -->width: <b>100px</b>; height: <b>100px</b>;
<!-- -->border: <b>12px solid blue</b>; background-color: <b>orange</b>;
<!-- -->border-top-left-radius: <b>60px 90px</b>;
<!-- -->border-bottom-right-radius: <b>60px 90px</b>;
<!-- -->box-shadow: <b>64px 64px 12px 40px rgba(0,0,0,0.4),
<!-- -->            12px 12px 0px 8px rgba(0,0,0,0.4) inset</b>;
    </pre>
    <p class="figure">
      <img src="images/spread-blur.png"
           alt="The sample code above would create a 100px&times;100px orange box with a 12px blue border,
                whose top right / bottom left corners are sharp and tob left / bottom right corners are elliptically curved.
                Two shadows are created: an inner one, which due to its offset and spread creates a 20px-wide band of darker orange along the top and left sides of the box (curving to match the rounded top left border shape);
                and an outer one, creating a 204px&times;204px gray duplicate of the shape seemingly behind the box,
                offset 24px down and 24px to the right of the box's top and left edges.
                Applying the 12px blur radius to the outer shadow creates a gradual shift from the shadow color to transparent along its edges
                which is visibly apparent for 24px centered along the edge of the shadow.">
    </p>
  </div>

<h4 id="shadow-shape">
Shadow Shape, Spread, and Knockout</h4>

  <p>An <i>outer box-shadow</i> casts a shadow as if the border-box of the element were opaque.
  Assuming a spread distance of zero, its perimeter has the exact same size and shape as the border box.
  The shadow is drawn outside the border edge only:
  it is clipped inside the border-box of the element.

  <p>An <i>inner box-shadow</i> casts a shadow as if everything outside the padding edge were opaque.
  Assuming a spread distance of zero, its perimeter has the exact same size and shape as the padding box.
  The shadow is drawn inside the padding edge only:
  it is clipped outside the padding box of the element.

  <p>If a <i>spread distance</i> is defined, the shadow perimeter defined above
  is expanded outward (for <i>outer box-shadows</i>) or contracted inward (for <i>inner box-shadows</i>)
  by outsetting (insetting, for inner shadows) the shadow's straight edges by the <i>spread distance</i>
  (and flooring the resulting width/height at zero).

  <div class="example">
    <p>Below are some examples of an orange box with a blue border being
      given a drop shadow.</p>

    <table class="data" id="box-shadow-samples">
      <tr>
        <th scope="rowgroup">
          <pre><code><!--
         -->border:5px solid blue;
<!--     -->background-color:orange;
<!--     -->width: 144px;
<!--     -->height: 144px;<!--
       --></code></pre>
        <th>
          <pre><code>border-radius: 20px;</code></pre>
        <th>
          <pre><code>border-radius: 0;</code></pre>
      <tr>
        <th>
          <pre><code><!--
         -->box-shadow:
<!--     -->  rgba(0,0,0,0.4)
<!--     -->  10px 10px;<!--
       --></code></pre>
        <td>
          <img src="images/shadow-outer-round.png" width="175" height="175"
               alt="A round-cornered box with a light gray shadow the same shape
                    as the border box offset 10px to the right and 10px down
                    from directly underneath the box.">
        <td>
          <img src="images/shadow-outer-square.png" width="175" height="175"
               alt="A square-cornered box with a light gray shadow the same shape
                    as the border box offset 10px to the right and 10px down
                    from directly underneath the box.">
      <tr>
        <th>
          <pre><code><!--
         -->box-shadow:
<!--     -->  rgba(0,0,0,0.4)
<!--     -->  10px 10px
<!--     -->  inset<!--
       --></code></pre>
        <td>
          <img src="images/shadow-inner-round.png" width="175" height="175"
               alt="A round-cornered box with a light gray shadow the inverse shape
                    of the padding box filling 10px in from the top and left edges
                    (just inside the border).">
        <td>
          <img src="images/shadow-inner-square.png" width="175" height="175"
               alt="A square-cornered box with a light gray shadow the inverse shape
                    of the padding box filling 10px in from the top and left edges
                    (just inside the border).">
      <tr>
        <th>
          <pre><code><!--
         -->box-shadow:
<!--     -->  rgba(0,0,0,0.4)
<!--     -->  10px 10px 0
<!--     -->  10px /* spread */<!--
       --></code></pre>
        <td>
          <img src="images/shadow-outer-spread-round.png" width="175" height="175"
               alt="A round-cornered box with a light gray shadow the same shape
                    as the box but 20px taller and wider and offset so that the
                    top and left edges of the shadow are directly underneath the
                    top and left edges of the box.">
        <td>
          <img src="images/shadow-outer-spread-square.png" width="175" height="175"
               alt="A square-cornered box with a light gray shadow the same shape
                    as the box but 20px taller and wider and offset so that the
                    top and left edges of the shadow are directly underneath the
                    top and left edges of the box.">
      <tr>
        <th>
          <pre><code><!--
         -->box-shadow:
<!--     -->  rgba(0,0,0,0.4)
<!--     -->  10px 10px 0
<!--     -->  10px /* spread */
<!--     -->  inset<!--
       --></code></pre>
        <td>
          <img src="images/shadow-inner-spread-round.png" width="175" height="175"
               alt="A round-cornered box with a light gray shadow the inverse shape
                    of the box but 20px narrower and shorter filling 20px in from
                    the top and left edges (just inside the border).">
        <td>
          <img src="images/shadow-inner-spread-square.png" width="175" height="175"
               alt="A round-cornered box with a light gray shadow the inverse shape
                    of the box but 20px narrower and shorter filling 20px in from
                    the top and left edges (just inside the border).">
      </tr>
    </table>
  </div>

  <p>To preserve the box's shape when spread is applied,
  the corner radii of the shadow are also increased (decreased, for inner shadows)
  from the border-box (padding-box) radii by adding (subtracting)
  the <i>spread distance</i> (and flooring at zero).
  However, in order to create a sharper corner when the border radius is small
  (and thus ensure continuity between round and sharp corners),
  when the <i>border radius</i> is less than the <i>spread distance</i>
  (or in the case of an inner shadow,
  less than the absolute value of a negative <i>spread distance</i>),
  the <i>spread distance</i>
  is first multiplied by the proportion 1 + (<var>r</var>-1)<sup>3</sup>,
  where <var>r</var> is the ratio of the border radius to the <i>spread distance</i>,
  in calculating the corner radii of the spread shadow shape.
  For example, if the border radius is 10px and the <i>spread distance</i> is 20px (<var>r</var> = .5),
  the corner radius of the shadow shape will be 10px + 20px × (1 + (.5 - 1)<sup>3</sup>) = 27.5px
  rather than 30px.
  This adjustment is applied independently to the radii in each dimension.

  <p>The 'border-image' does not affect the shape of the box-shadow.

<h4 id="shadow-blur">
Blurring Shadow Edges</h4>

  <p>A non-zero <i>blur radius</i> indicates that the resulting shadow should
  be blurred, such as by a Gaussian filter. The exact algorithm is not
  defined; however the resulting shadow must approximate (with each pixel
  being within 5% of its expected value) the image that would be generated
  by applying to the shadow a Gaussian blur with a standard deviation equal
  to half the blur radius

  <p class="note">Note this means for a long, straight shadow edge, the
  blur radius will create a visibly apparent color transition approximately
  the twice length of the blur radius that is perpendicular to and centered
  on the shadow's edge, and that ranges from almost the full shadow color at the
  endpoint inside the shadow to almost fully transparent at the endpoint outside it.

<h4 id="shadow-layers">
Layering, Layout, and Other Details</h4>

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

  <p>If an element has multiple boxes, all of them get drop shadows,
  but shadows are only drawn where borders would also be drawn;
  see 'box-decoration-break'.

  <p>Shadows do not trigger scrolling or increase the size of the scrollable area.

  <p>Outer shadows have no effect on internal table elements in the collapsing border model.
  If a shadow is defined for single border edge in the collapsing border model
  that has multiple border thicknesses
  (e.g. an outer shadow on a table where one row has thicker borders than the others,
  or an inner shadow on a rowspanning table cell that adjoins cells with different border thicknesses),
  the exact position and rendering of its shadows are undefined

<h2 id="definitions">Definitions</h2>


<h3 id="glossary">Glossary</h3>

<p>The following terms and abbreviations are used in this
module.

<dl>
<dt><dfn>UA</dfn>
<dt><dfn id="user-agent">user agent</dfn>
<dd>
<p>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 <span>documents</span> (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.)

<dt><dfn title="document|documents">document</dfn>
<dd>
<p>A tree-structured document with elements and attributes, such as an
SGML or XML document [[XML11]].

<dt><dfn>style sheet</dfn>
<dd>
<p>A <a href="https://www.w3.org/TR/CSS2/conform.html#style-sheet">CSS style sheet</a>.
</dl>

<h3 id="levels">Levels</h3>

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

<h4 id="level-1">Level 1</h4>
<ul>
  <li>'background-color'
  <li>'background-image' only one image (no layers)
  <li>'background-repeat': only ''background-repeat/repeat'' | ''repeat-x'' | ''repeat-y'' | ''no-repeat''
  <li>'background-attachment': only ''scroll'' | ''fixed''
  <li>'background-position': only one or two values allowed
  <li>'background' shorthand: only color, image, repeat, attachment and position
  <li>'border-color' properties
  <li>'border-style' properties
  <li>'border-width' properties
  <li>'border-top', 'border-bottom', 'border-right', 'border-left', and 'border' shorthands
</ul>

<h4 id="level-2">Level 2</h4>
<ul>
  <li>'background-color'
  <li>'background-image': only one image (no layers)
  <li>'background-repeat': only ''background-repeat/repeat'' | ''repeat-x'' | ''repeat-y'' | ''no-repeat''
  <li>'background-attachment': only ''scroll'' | ''fixed''
  <li>'background-position': only one or two values allowed
  <li>'background': only color, image, repeat, attachment and position
  <li>'border-color' properties
  <li>'border-style' properties
  <li>'border-width' properties
  <li>'border-top', 'border-bottom', 'border-right', 'border-left', and 'border' shorthands
</ul>

<h4 id="level-3">Level 3</h4>
<ul>
  <li>All features described in the CSS Backgrounds and Borders Module Level 3
</ul>


<h2 id="changes">
Changes</h2>

<h3 id="changes-2020-12">
Changes since the 22 December 2020 Candidate Recommendation Snapshot</h3>

<ul>
  <li>Clarified that the rule about not propagating backgrounds from the root
    when it doesn't generate boxes only applies to ''display: none'',
    not ''display: contents''.
    (<a href="https://github.com/w3c/csswg-drafts/issues/3779">Issue 3779</a>)
</ul>

<h3 id="changes-2017-10">
Changes since the 17 October 2017 Candidate Recommendation</h3>

<ul>
  <li>
    Inverted order of <<shadow>> grammar to match browser serialization and 'text-shadow'/''drop-shadow()''.
      (<a href="https://github.com/w3c/csswg-drafts/issues/2305">Issue 2305</a>)
      <blockquote>
        <pre><<shadow>> = <del>inset</del><ins><<color>></ins>? &amp;&amp; <<length>>{2,4} &amp;&amp; <del><<color>></del><ins>inset</ins>?</pre>
      </blockquote>
  <li>
    Spread radius adjustment is only applied to shadows and margins
    where the radius of curvature grows, rather than shrinks.
    (<a href="https://github.com/w3c/csswg-drafts/issues/1900">Issue 1900</a>)
      <blockquote>
        <p>To preserve the box's shape when spread is applied,
        the corner radii of the shadow are also increased (decreased, for inner shadows)
        from the border-box radii by adding (subtracting)
        the <i>spread distance</i> (and flooring at zero).
        However, in order to create a sharper corner when the border radius is small
        <ins>(and thus ensure continuity between round and sharp corners)</ins>,
        when the <i>border radius</i> is less than the <i>spread distance</i>
        <ins>(or in the case of an inner shadow,
        less than the absolute value of a negative <i>spread distance</i>)</ins>,
        the <i>spread distance</i>
        is multiplied by the proportion 1 + (<var>r</var>-1)<sup>3</sup>,
        where <var>r</var> is the ratio of the border radius to the <i>spread distance</i>,
        in calculating the corner radii of the spread shadow shape.
      </blockquote>
  <li>
    Clarified that an omitted <<color>> in a <<shadow>> defaults to ''currentColor'',
    not some mysterious unnamed value with the same behavior.
    (<a href="https://github.com/w3c/csswg-drafts/issues/2766">2766</a>)
    <blockquote>
      <p>If the color is absent, <ins>it defaults to ''currentColor''</ins>
      <del>the used color is taken from the 'color' property.</del>
    </blockquote>
  <li>
    Cleaned up and regularized “Animation type” and “Computed value” lines
    in the property definition tables.
  <li>
    Changed syntax to use the new <a>CSS bracketed range notation</a>
    to reflect the prose restrictions on negative values,
    and corrected a few grammar definition errors introduced in the previous publication.
  <li>
    Minor editorial improvements.
</ul>

<h3 id="changes-2014-09">
Changes since the 9 September 2014 Candidate Recommendation</h3>

<p>The following (non-trivial) changes were made to this specification since the
<a href="https://www.w3.org/TR/2014/CR-css3-background-20140909/">9 September 2014 Candidate Recommendation</a>:
<ul>
  <li>Added missing definition of ''box-shadow: none''.
  (Apparently this was obvious enough that nobody noticed it was missing until now.)
  <li>Moved <<'background-color'>> component of <<final-bg-layer>> to the front for serialization
  because some authors seem to expect this even though it makes less sense?
  <li>Dropped effect of 'border-radius' from collapsed-borders tables.
  <li>Renamed <<position>> back to <<bg-position>>
      since other properties will be eliding the three-value syntax.
</ul>

<h3 id="changes-2014-02">
Changes since the 4 February 2014 Last Call Working Draft</h3>

<p>The following (non-trivial) changes were made to this specification since the
<a href="https://www.w3.org/TR/2014/WD-css3-background-20140204/">4 February 2014 Last Call Working Draft</a>:
<ul>
  <li>Fixed spread radius and margin radius calculations
  to only apply adjustment factor when spread/margin is larger than border radius.
  <li>Defined handling of canvas background when root element has ''display: none''.
</ul>

<p>A full <a href="https://drafts.csswg.org/css-backgrounds-3/issues-lc-2014">Disposition of Comments</a> is available.

<h3 id="changes-2012-07">
Changes since the 24 July 2012 Candidate Recommendation</h3>

<p>The following (non-trivial) changes were made to this specification since the
<a href="https://www.w3.org/TR/2012/CR-css3-background-20120724/">24 July 2012 Candidate Recommendation</a>:

<ul>
  <li>Allow <<'background-clip'>> and <<'background-origin'>>
    to be separated by other component values in the 'background' shorthand,
    since this is what is implemented.
  <li>Allow <<color>> and ''box-shadow/inset'' to be interleaved in any order in 'box-shadow',
    since they are not ambiguous and CSS generally allows variant ordering where not ambiguous.
  <li>Define gradually increasing corner radius formula for 'box-shadow' spread curvature
    to create continuity between sharp corners ('border-radius' = 0)
    and curved corners ('border-radius' > <var>spread distance</var>).
    This also gives better results for all intermediate states.
  <li>Add definition for how the margin edge is curved in response to border-radius.
    (This is relevant for [[CSS-SHAPES]], but does not change conformance to CSS Backgrounds and Borders Level 3.)
  <li>Removed 'box-decoration-break'; it is now part of [[CSS3-BREAK]].
  <li>Tighten up the definition of spread for 'box-shadow'.
  <li>Clarify that a 'border-style' of ''border-style/none'' also implies an initial 'border-image-width' of zero
    (since 'border-image-width' is initially set to the computed 'border-width', which in this case is zero).
  <li>Clarified how ''background-attachment: local'' is affected by scrolling.
  <li>Simplified computed value of 'background-position'
    to clarify that all 'background-position' values are interpolable.
  <li>Added “Animatable” values to each property definition table.
</ul>

<h3 id="changes-2012-04">
Changes since the 17 April 2012 Candidate Recommendation</h3>

<p>The following (non-editorial) changes were made to this specification since the
<a href="https://www.w3.org/TR/2012/CR-css3-background-20120417/">17
April 2012 Candidate Recommendation</a>:

<ul>
  <li>Fix error in computed value of 'background-position':
    the computed value is a list of positions.
  <li>Add a note pointing out that when 'border-radius' reduces
    the interactive area, the width/height of the box might need to be increased.
</ul>

<h3 id="changes-2012LC">
Changes since the 14 February 2012 “Last Call” Working Draft</h3>

<p>The following (non-editorial) changes were made to this
specification since the <a href="https://www.w3.org/TR/2012/WD-css3-background-20120214/">14 February 2012 “Last Call” Working Draft</a>:

<p>These changes were in response to comments received during the
review period. For details, see the full <a href="https://drafts.csswg.org/css-backgrounds-3/issues-lc-2012">Disposition of Comments.</a>

<ul>
  <li><a href="#placement">Section 2.1</a>: Defined which properties
  from this module apply to the ''::first-line'' and
  ''::first-letter'' pseudo-elements.

  <li><a href="#the-background-repeat">Section 3.4</a>: Fixed the
  incorrect definition of the computed value of
  'background-repeat'. The value is always a pair of keywords, never a
  single keyword.

  <li><a href="#the-background">Section 3.10</a>: Added the missing
  'background-image' to the list of properties that the 'background'
  property reset.

  <li><a href="#the-border-width">Section 4.3</a>: Added that negative
  lengths are invalid on 'border-width'.

  <li><a href="#the-border-radius">Section 5.1</a>: Added that
  negative lengths are invalid on 'border-radius'.

  <li><a href="#border-image-tables">Section 6.8</a>: Added a section
  about the effect of 'border-image' on tables with collapsed borders
  and added that the rendering will be defined later.
</ul>

<h3 id="changes-2011">
Changes Since the 15 February 2011 Candidate Recommendation</h3>

<p>The following changes were made to this specification since the
<a href="https://www.w3.org/TR/2011/CR-css3-background-20110215/">15 February 2011
Candidate Recommendation</a>:

<ul>
  <li><a href="#the-background-size">Section 3.9</a>:
    Defined what happens if 'background-size' has two ''background-size/auto'' values
    and the image is missing a natural size.
    <blockquote>
    <p>If both values are ''background-size/auto'' then the natural width and/or
    height of the image should be used, if any<ins>, the missing
    dimension (if any) behaving as ‘auto’ as described above</ins>.
    </blockquote>
  <li><a href="#corner-transitions">Section 5.4</a>:
    Made center of <a href="#corner-transitions">color and style transitions</a>
    undefined (within certain limits) on corner joins, since previous definition
    was wrong.
    <blockquote>
    <p><del>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 top and right border widths are equal, that point
    is at a 45° angle from the horizontal, and if the top is twice the
    width of the right the point is at a 30° angle from the
    horizontal. The line demarcating this transition is drawn between
    the point at that angle on the outer arc and the point at that
    angle on the inner arc.</del>
    <p><ins>If one of these borders is zero-width, then the other
    border takes up the entire transitional area. Otherwise, the
    center of color and style transitions between adjoining borders
    must be proportional to the ratio of the border widths such that a
    function of its location is continuous with respect to this ratio.
    However it is not defined what these transitions look like or how
    &ldquo;proportional&rdquo; maps to a point on the curve.</ins>
    </blockquote>
  <li><a href="#the-border-image-slice">Section 6.2</a>:
    Defined <a href="#the-border-image-slice">slicing of border images</a>
    that must be sized first to determine slice positions.
    Added:
    <blockquote>
    <p><ins>If the image must be sized to determine the slices (for
    example, for SVG images with no natural size), then it is sized
    as for an auto-sized background, using the border image area as
    the default object size in place of the background positioning
    area.</ins>
    </blockquote>
  <li><a href="#misc">Section 7.1</a>
    Optionally added bidi-imposed breaks to the types of breaks affected by
      'box-decoration-break'.
    Added:
    <blockquote>
    <p><ins>UAs may also apply ‘box-decoration-break’ to control
    rendering at bidi-imposed breaks, i.e. when bidi reordering causes
    an inline to split into non-contiguous fragments. Otherwise such
    breaks are always handled as ‘slice’.</ins>
    </blockquote>
  <li><a href="#the-box-shadow">Section 7.2</a>:
    Defined the default color of 'box-shadow'.
    <blockquote>
    <p>The color is the color of the shadow. <ins>If the color is
    absent, the used color is taken from the ‘color’ property.</ins>
    </blockquote>
  <li><a href="#the-background-position">Section 3.6</a>:
    Clarified computed value of 'background-position'.
    <blockquote>
    <p><del>If one or two values are specified, for a &lt;length> the
    absolute length, otherwise a percentage. If three or four values
    are specified, two pairs of a keyword plus a length or
    percentage.</del> <ins>Two keywords representing the origin and
    two offsets from that origin, each given as an absolute length (if
    given a <<length>>), otherwise as a percentage.</ins>
    </blockquote>
    <p>Changed <del>Equivalent</del> to <ins>Computes</ins> in
    definition of keywords.
  <li><a href="#animations">Section 2.3</a> (and all property definitions):
    Added a section about expected an expected animations module.
    Added "Animatable" line to property definition tables.
  <li><a href="#the-background-position">Section 3.6</a>:
    Renamed &lt;bg-position&gt; production to <i>&lt;position&gt;</i> for
    easier re-use in other specifications and recast the grammar to be more
    verbose but easier to understand.
    <blockquote>
    <pre class=prod>
      <del>bg-position</del><ins>&lt;position&gt;</ins> = [
        [ <ins>left | center | right |</ins> top | bottom <ins>| <<length-percentage>></ins> ]
      |
        [ left | center | right | <<length-percentage>> ]
        [ top | center | bottom | <<length-percentage>> ]<del>?</del>
      |
        [ center | [ left | right ] <<length-percentage>>? ] &amp;&amp;
        [ center | [ top | bottom ] <<length-percentage>>? ]
      ]
    </pre>
    </blockquote>
  <li><a href="#the-border-image-repeat">Section 6.5</a>:
    Added ''border-image-repeat/space'' keyword to 'border-image-repeat' property value table:
    it was included in the list of allowable values, but not in the syntax
    definition.
    <blockquote>
    <p>[ stretch | repeat | round <ins>| space</ins> ]{1,2}
    </blockquote>
  <li><a href="#corner-overlap">Section 5.5</a>:
    Corrected math error in border-radius example.
    <blockquote>
    <p>The height (2.5em) is enough for the specified radii (0.5em
    plus <del>2.5em</del> <ins>2.0em</ins>).
    </blockquote>
  <li><a href="#the-border-width">Section 4.3</a>:
    Marked Percentages field as N/A for 'border-width', since they are not
    included in the property.
</ul>

<h3 id="changes-2009">
Changes Since the 17 December 2009 Candidate Recommendation</h3>

<p>The following changes were made to this specification since the
<a href="https://www.w3.org/TR/2009/CR-css3-background-20091217/">17 December 2009
Candidate Recommendation</a>:

<ul>
  <li>Addition of ''background-clip/content-box'' value of 'background-clip'.
  <li>Change to the 'background' shorthand syntax for 'background-clip'
      and 'background-origin'.
  <li>Removal of recommendation to use gradients for color transitions
      when 'border-radius' produces a curve.
  <li>(Re)Addition of ''box-shadow'' property.
  <li>Various clarifications.
</ul>

<h2 id="acknowledgments">Acknowledgments</h2>

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

<p>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; to Zack Weinberg for the corner transition regions diagram;
and to Lea Verou, plinss, and dbaron for the corner radius adjustment formula
(with special thanks to Lea for the live demo).

<p>A set of properties for border images was initially proposed by
<em>fantasai.</em> 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.)

<p>Finally, special thanks go to Brad Kemper for his feedback and
suggestions for many of the features in the draft, for drawing all
the box-shadow examples, and for proposing some
<a href="http://www.bradclicks.com/cssplay/border-image/Thinking_Outside_The_Box.html">radical changes</a>
to the 'border-image' property that solved a number of problems with
the earlier definition.</p>