border-image

  • Revision slug: CSS/border-image
  • Revision title: border-image
  • Revision id: 14218
  • Created:
  • Creator: teoli
  • Is current revision? No
  • Comment one or more formatting changes

Revision Content

{{ CSSRef() }}

Summary

The border-image CSS property allows drawing an image on the borders of elements. This makes drawing complex looking widgets much simpler than it has been and removes the need for nine boxes in some cases.

The border-image is used instead of the border styles given by the {{ cssxref("border-style") }} properties.  If the value is none or if the image cannot be displayed, the border styles will be used. An additional background image for the element is drawn on top of the {{ Cssxref("background-image") }}.

<style type="text/css"></style>
  • {{ Xref_cssinitial() }}: {{ Cssxref("none") }}
  • Applies to: all elements, except table elements when {{ cssxref("border-collapse") }} is collapse
  • {{ Xref_cssinherited() }}: no
  • Media: {{ Xref_cssvisual() }}
  • {{ Xref_csscomputed() }}: any URI made absolute, any {{ Xref_csslength() }} made absolute, other parts as specified

Syntax

none |
  <image> || [[<number> | <percentage> ]{1,4} && fill?] [[/ [<length> | <percentage> | <number> | auto ]{1,4} ]? [/ [<length> | <number> ]{1,4}]?]
  || [ stretch | repeat | round | space ]{1,2}

That is,

none |
  <‘border-image-source’> || <‘border-image-slice’> [ / <‘border-image-width’>? [ / <‘border-image-outset’> ]? ]?
  || <‘border-image-repeat’>

Values

none
No image displayed; other border styles are used.

border-image-source

The image to use for the border.

<image> (required)
The image value is a {{ Xref_cssuri() }}, e.g. url(http://example.org/image.png)

border-image-slice

border-image-width

<number> | <percentage> (required)

One, two, three or four values represent inward offsets from the top, right, bottom and left edges of the image (respectively), dividing it into nine regions: four corners, four edges, and a middle.

One value belongs to all four sides of the image.
Two values belong 1. to the top and bottom and 2. to the right and left sides.
Three values belong 1. to the top, 2. to the right and left sides, and 3. to the bottom.
Four values belong to the top, right, bottom, and left sides, in that order.

Percentages are relative to the width/height of the image.
Numbers represent pixels in the image (if the image is a raster image) or vector coordinates (if the image is an SVG image).

Negative values are not allowed.
Values greater than the size of the image are interpreted as 100%.

fill (optional)
If the "fill" keyword is present, the middle part of the border-image is preserved, and drawn as the background-image of the image. In Gecko 1.9.1 (Firefox 3.5) this is the default behaviour; in Gecko 12, the default behaviour is to discard this area.
<number> | <percentage> | auto (required)

The border image is drawn inside an area (the border image area) the boundaries of which correspond by default to the border box (which may be changed by border-image-outset). The four values specify the inward distances from the top, right, bottom and left edges of the image (respectively).

One value belongs to all four sides of the area.
Two values belong 1. to the top and bottom and 2. to the right and left sides.
Three values belong 1. to the top, 2. to the right and left sides, and 3. to the bottom.
Four values belong to the top, right, bottom, and left sides, in that order.

Percentages refer to the width and height of the border image area (as appropriate).
Numbers represent multiples of the corresponding computed border-width.
auto means that the intrinsic width/height (as applicable) of the corresponding image slice (border-image-slice) is used. If this is not available, then the border-width values are used.

Negative values are not allowed.

border-image-outset

<length> | <number> (required)

The border-image-outset values specify the amount by which the border-image-area extends beyond the border box. Its four values specify the outsets for the top, right, bottom and left edges of the box.

One value belongs to all four sides of the box.
Two values belong 1. to the top and bottom and 2. to the right and left sides.
Three values belong 1. to the top, 2. to the right and left sides, and 3. to the bottom.
Four values belong to the top, right, bottom, and left sides, in that order.

Numbers represent multiples of the corresponding computed border-width.

Negative values are not allowed.

Note: outset images may be clipped by an ancestor or by the viewport, so you may need to use other properties (such as margins) if you wish to ensure that the full border-image is displayed.

border-image-repeat

<stretch> | <repeat> | <round> | <space> (required)

Specifies how the images for the sides and the middle part of the border-image are scaled and tiled.

One value belongs to both the horizontal and vertical sides.
Two values belong to 1. the horizontal sides, and 2. the vertical sides.

stretch specifies that the image should be stretched to fill the area.
repeat indicates that the image should be tiled (repeated) to fill the area.
round means that the image is tiled to fill the area; if a whole number of tiles cannot be used to fill the area, the image is rescaled such that a whole number of tiles may be used.
space specifies that the image should be tiled to fill the area; if a whole number of tiles cannot be used to fill the area, the extra space is distributed around the tiles.

Examples

[needs some instructive live examples]

Browser compatibility

Note:  Features beyond basic support are not yet documented in above sections. Please read the spec if you are interested.
Note: An earlier version of the specification was implemented in Gecko versions prior to 12. 

{{ CompatibilityTable() }}

Feature Firefox (Gecko) Chrome Internet Explorer Opera Safari
Basic support {{ CompatGeckoDesktop("1.9.1") }}{{ property_prefix("-moz") }} 7.0{{ property_prefix("-webkit") }} {{ CompatNo() }} 10.5 / 11.0{{ property_prefix("-o") }} 3.0{{ property_prefix("-webkit") }}
optional <border-image-slice> {{ CompatGeckoDesktop("12") }} {{ CompatUnknown() }} {{ CompatNo() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
fill keyword {{ CompatGeckoDesktop("12") }} {{ CompatUnknown() }} {{ CompatNo() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
Feature iOS Safari Opera Mini Opera Mobile Android Browser
Basic support 3.2{{ property_prefix("-webkit") }} {{ CompatNo() }} 11.0{{ property_prefix("-o") }} 2.1{{ property_prefix("-webkit") }}
optional <border-image-slice> {{ CompatUnknown() }} {{ CompatNo() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
fill keyword {{ CompatUnknown() }} {{ CompatNo() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

Notes

  • Unusually, for Opera, the prefixed property was added after the non-prefixed.

Specifications

{{ languages( { "zh-tw": "zh_tw/CSS/-moz-border-image"} ) }}

Revision Source

<div>{{ CSSRef() }}</div> <h2>Summary</h2>
<p>The<code> border-image </code>CSS property allows drawing an image on the borders of elements. This makes drawing complex looking widgets much simpler than it has been and removes the need for nine boxes in some cases.</p>
<p>The<code> border-image </code>is used instead of the border styles given by the {{ cssxref("border-style") }} properties.  If the value is<code> none </code>or if the image cannot be displayed, the border styles will be used. An additional background image for the element is drawn on top of the {{ Cssxref("background-image") }}.</p>
<nobr>
<style type="text/css"><![CDATA[.cssprop {
  display:table;
  padding: 0.4em;
  border-left:0.15em solid;
  background-color:#eeeeff
}
.cssprop li {
 display:table-row;
 padding: 3px;
 margin:0;
}
.cssprop li dfn {
  display:table-cell;
  padding: 0 5px;
  border-bottom: none;
  cursor:inherit;
}

]]></style>
<ul class="cssprop"> <li><dfn>{{ Xref_cssinitial() }}:</dfn> {{ Cssxref("none") }}</li> <li><dfn>Applies to:</dfn> all elements, except table elements when {{ cssxref("border-collapse") }} is<code> <code class="css">collapse</code></code></li> <li><dfn>{{ Xref_cssinherited() }}:</dfn> no</li> <li><dfn>Media:</dfn> {{ Xref_cssvisual() }}</li> <li><dfn>{{ Xref_csscomputed() }}:</dfn> any URI made absolute, any {{ Xref_csslength() }} made absolute, other parts as specified</li>
</ul>
</nobr><h2>Syntax</h2>
<pre class="eval">none |
  &lt;image&gt; || [[&lt;number&gt; | &lt;percentage&gt; ]{1,4} &amp;&amp; fill?] [[/ [&lt;length&gt; | &lt;percentage&gt; | &lt;number&gt; | auto ]{1,4} ]? [/ [&lt;length&gt; | &lt;number&gt; ]{1,4}]?]
  || [ stretch | repeat | round | space ]{1,2}
</pre>
<p>That is,</p>
<pre class="eval"><em>none |
  &lt;‘border-image-source’&gt; || &lt;‘border-image-slice’&gt; [ / &lt;‘border-image-width’&gt;? [ / &lt;‘border-image-outset’&gt; ]? ]?
  || &lt;‘border-image-repeat’&gt;</em>
</pre>
<h3>Values</h3>
<dl> <dt><code>none</code></dt> <dd>No image displayed; other border styles are used.</dd>
</dl>
<h4>border-image-source</h4>
<p>The image to use for the border.</p>
<dl> <dt><code>&lt;image&gt;</code> <small>(required)</small></dt> <dd>The image value is a {{ Xref_cssuri() }}, e.g. <code>url(<a class=" external" href="http://example.org/image.png" rel="freelink">http://example.org/image.png</a>)</code></dd>
</dl>
<h4>border-image-slice</h4>
<h4>border-image-width</h4>
<dl> <dt><code>&lt;number&gt;</code> | <code>&lt;percentage&gt;</code> <small>(required)</small></dt> <dd> <p>One, two, three or four values represent inward offsets from the top, right, bottom and left edges of the image (respectively), dividing it into nine regions: four corners, four edges, and a middle.<img alt="" src="/@api/deki/files/3683/=slice.png" style="float: right;"><br> <br> One value belongs to all four sides of the image.<br> Two values belong 1. to the top and bottom and 2. to the right and left sides.<br> Three values belong 1. to the top, 2. to the right and left sides, and 3. to the bottom.<br> Four values belong to the top, right, bottom, and left sides, in that order.<br> <br> <strong>Percentages</strong> are relative to the width/height of the image.<br> <strong>Numbers</strong> represent pixels in the image (if the image is a raster image) or vector coordinates (if the image is an SVG image).<br> <br> Negative values are not allowed.<br> Values greater than the size of the image are interpreted as 100%.</p> </dd> <dt>fill<small> (optional)</small></dt> <dd>If the "fill" keyword is present, the middle part of the border-image is preserved, and drawn as the background-image of the image. In Gecko 1.9.1 (Firefox 3.5) this is the default behaviour; in Gecko 12, the default behaviour is to discard this area.</dd>
</dl>
<dl> <dt>&lt;number&gt; | &lt;percentage&gt; | auto <small>(required)</small></dt> <dd> <p>The border image is drawn inside an area (the <em>border image area</em>) the boundaries of which correspond by default to the border box (which may be changed by border-image-outset). The four values specify the inward distances from the top, right, bottom and left edges of the image (respectively).<br> <br> One value belongs to all four sides of the area.<br> Two values belong 1. to the top and bottom and 2. to the right and left sides.<br> Three values belong 1. to the top, 2. to the right and left sides, and 3. to the bottom.<br> Four values belong to the top, right, bottom, and left sides, in that order.<br> <br> <strong>Percentages</strong> refer to the width and height of the border image area (as appropriate).<br> <strong>Numbers</strong> represent multiples of the corresponding computed border-width.<br> <strong>auto</strong> means that the intrinsic width/height (as applicable) of the corresponding image slice (border-image-slice) is used. If this is not available, then the border-width values are used.<br> <br> Negative values are not allowed.</p> </dd>
</dl>
<h4>border-image-outset</h4>
<dl> <dt><code>&lt;length&gt;</code> | <code>&lt;number&gt;</code> <small>(required)</small></dt> <dd> <p>The border-image-outset values specify the amount by which the <em>border-image-area</em> extends beyond the border box. Its four values specify the outsets for the top, right, bottom and left edges of the box.<br> <br> One value belongs to all four sides of the box.<br> Two values belong 1. to the top and bottom and 2. to the right and left sides.<br> Three values belong 1. to the top, 2. to the right and left sides, and 3. to the bottom.<br> Four values belong to the top, right, bottom, and left sides, in that order.<br> <br> <strong>Numbers</strong> represent multiples of the corresponding computed border-width.<br> <br> Negative values are not allowed.</p> </dd>
</dl>
<div>Note: outset images may be clipped by an ancestor or by the viewport, so you may need to use other properties (such as margins) if you wish to ensure that the full border-image is displayed.</div>
<h4>border-image-repeat</h4>
<dl> <dt><code>&lt;stretch&gt;</code> | <code>&lt;repeat&gt;</code> | <code>&lt;round&gt;</code> | <code>&lt;space&gt;</code> <small>(required)</small></dt> <dd> <p>Specifies how the images for the sides and the middle part of the border-image are scaled and tiled.<br> <br> One value belongs to both the horizontal and vertical sides.<br> Two values belong to 1. the horizontal sides, and 2. the vertical sides.<br> <br> <strong>stretch</strong> specifies that the image should be stretched to fill the area.<br> <strong>repeat</strong> indicates that the image should be tiled (repeated) to fill the area.<br> <strong>round</strong> means that the image is tiled to fill the area; if a whole number of tiles cannot be used to fill the area, the image is rescaled such that a whole number of tiles may be used.<br> <strong>space</strong> specifies that the image should be tiled to fill the area; if a whole number of tiles cannot be used to fill the area, the extra space is distributed around the tiles.</p> </dd>
</dl>
<h2>Examples</h2>
<p>[needs some instructive live examples]</p>
<h2>Browser compatibility</h2>
<div class="note"><strong>Note:</strong>  Features beyond basic support are not yet documented in above sections. Please read the spec if you are interested.</div>
<div class="note"><strong>Note:</strong> An earlier version of the specification was implemented in Gecko versions prior to 12. </div>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Firefox (Gecko)</th> <th>Chrome</th> <th>Internet Explorer</th> <th>Opera</th> <th>Safari</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatGeckoDesktop("1.9.1") }}{{ property_prefix("-moz") }}</td> <td>7.0{{ property_prefix("-webkit") }}</td> <td>{{ CompatNo() }}</td> <td>10.5 / 11.0{{ property_prefix("-o") }}</td> <td>3.0{{ property_prefix("-webkit") }}</td> </tr> <tr> <td>optional <code>&lt;border-image-slice&gt;</code></td> <td>{{ CompatGeckoDesktop("12") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> <tr> <td><code>fill</code> keyword</td> <td>{{ CompatGeckoDesktop("12") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
<div id="compat-mobile"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>iOS Safari</th> <th>Opera Mini</th> <th>Opera Mobile</th> <th>Android Browser</th> </tr> <tr> <td>Basic support</td> <td>3.2{{ property_prefix("-webkit") }}</td> <td>{{ CompatNo() }}</td> <td>11.0{{ property_prefix("-o") }}</td> <td>2.1{{ property_prefix("-webkit") }}</td> </tr> <tr> <td>optional <code>&lt;border-image-slice&gt;</code></td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> <tr> <td><code>fill</code> keyword</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
<h3>Notes</h3>
<ul> <li>Unusually, for Opera, the prefixed property was added <em>after</em> the non-prefixed.</li>
</ul>
<h2>Specifications</h2>
<ul> <li><a class="external" href="http://www.w3.org/TR/css3-background/#border-images" title="http://www.w3.org/TR/css3-background/#border-images">CSS 3 Backgrounds and borders #border-image</a></li>
</ul>
<p>{{ languages( { "zh-tw": "zh_tw/CSS/-moz-border-image"} ) }}</p>
Revert to this revision