border-image

  • Revision slug: CSS/border-image
  • Revision title: border-image
  • Revision id: 14213
  • Created:
  • Creator: leaverou
  • Is current revision? No
  • Comment 1 words added, 1 words removed

Revision Content

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.

Warning: The official CSS 3 specification for the border-image property changed significantly between the time this feature was frozen for Gecko 1.9.1 and its release. As such, both the syntax and semantics of this feature will probably change in future releases of Gecko. In particular, the optional border-width override has been removed from the specification and will almost certainly be removed in a future version of Gecko.

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

  • {{ 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 <length> made absolute, other parts as specified

Syntax

none | 
  [ <image> [ <number> | <percentage> ]{1,4} [/ <border-width>{1,4}]? ] && [ stretch | repeat | round ]{0,2} 

Values

none
No image displayed, other border styles are used.
<image> (required)
The image value is a {{ Xref_cssuri() }}, e.g. url(http://example.org/image.png)
<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 top and bottom and 2. to right and left side.
Three values belong 1. to top, 2. to the right and left side and 3. to bottom.
Four values belong to the top, right, bottom and left edge of the image in that order.

In Gecko 1.9.1 (Firefox 3.5) the middle part of the image is drawn like a background-image of the element. This may change in future versions.

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).
<border-width> (optional)
If the slash / is present in the property value, the one, two, three or four values after it are used for the width of the border instead of the {{ cssxref("border-width") }} properties. The order of the values is the same as for {{ cssxref("border-width") }}.
stretch | round | repeat (optional)
One or two keywords, that specify how the images for the sides and the middle part are scaled and tiled.
stretch  (default value) will cause images to be scaled to fit their box.
round    will tile the images, but also scale them so that a whole number fit in the box.
repeat   simply tiles the images inside the box.
The first keyword describes how to draw the top, middle, and bottom images, while the second describes the left and right borders. If the second is absent, it is assumed to be the same as the first. If both are absent, the default value stretch is used.

Examples

[needs some instructive live examples]

#header  { -moz-border-image: url(border.png) 27 27 27 27 round round; } 

.button  { -moz-border-image: url(button.png) 0 5 0 5; }

.example { -moz-border-image: url(example.jpg) 3 4 6 8 / 10px 12px 14px 22px; }
/* Edge case, acts like a full scaled background-image in Firefox 3.5 */

 div     { -moz-border-image: url(bgimage.png) 0; } 

Browser compatibility

Note:  Features beyond basic support are not yet documented in above sections. Please read the spec if you are interested.

{{ 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> {{ CompatNo() }}
{{ unimplemented_inline("497995") }}
{{ CompatUnknown() }} {{ CompatNo() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
fill keyword {{ CompatNo() }} {{ 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

<h3>Summary</h3>
<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>
<div class="warning"><strong>Warning:</strong> The official CSS 3 specification for the border-image property changed significantly between the time this feature was frozen for Gecko 1.9.1 and its release. As such, both the syntax and semantics of this feature will probably change in future releases of Gecko. In particular, the optional<code> border-width </code>override has been removed from the specification and will almost certainly be removed in a future version of Gecko.</div>
<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>
<ul> <li>{{ Xref_cssinitial() }}: {{ Cssxref("none") }}</li> <li>Applies to: all elements, except table elements when {{ cssxref("border-collapse") }} is<code> <code class="css">collapse</code></code></li> <li>{{ Xref_cssinherited() }}: no</li> <li>Media: {{ Xref_cssvisual() }}</li> <li>{{ Xref_csscomputed() }}: any URI made absolute, any &lt;length&gt; made absolute, other parts as specified</li>
</ul>
<h3>Syntax</h3>
<pre class="eval">none | 
  [ &lt;image&gt; [ &lt;number&gt; | &lt;percentage&gt; ]{1,4} [/ &lt;border-width&gt;{1,4}]? ] &amp;&amp; [ stretch | repeat | round ]{0,2} </pre>
<h3>Values</h3>
<dl> <dt>none</dt> <dd>No image displayed, other border styles are used.</dd> <dt>&lt;image&gt; <small>(required)</small></dt> <dd>The image value is a {{ Xref_cssuri() }}, e.g.<code class="plain"> url(http://example.org/image.png)</code></dd> <dt>&lt;number&gt; | &lt;percentage&gt; <small>(required)</small></dt> <dd>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.<br> <img alt="" src="/@api/deki/files/3683/=slice.png" style="float:right"><br> One value belongs to all four sides of the image.<br> Two values belong 1. to top and bottom and 2. to right and left side.<br> Three values belong 1. to top, 2. to the right and left side and 3. to bottom.<br> Four values belong to the top, right, bottom and left edge of the image in that order.<br> <br> In Gecko 1.9.1 (Firefox 3.5) the middle part of the image is drawn like a background-image of the element. This may change in future versions.<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).</dd> <dt>&lt;border-width&gt; <small>(optional)</small></dt> <dd>If the slash <strong>/</strong> is present in the property value, the one, two, three or four values after it are used for the width of the border instead of the {{ cssxref("border-width") }} properties. The order of the values is the same as for {{ cssxref("border-width") }}.</dd> <dt>stretch | round | repeat <small>(optional)</small></dt> <dd>One or two keywords, that specify how the images for the sides and the middle part are scaled and tiled.<br> <strong><code>stretch  </code></strong>(default value) will cause images to be scaled to fit their box.<br> <strong><code>round    </code></strong>will tile the images, but also scale them so that a whole number fit in the box.<br> <strong><code>repeat   </code></strong>simply tiles the images inside the box.<br> The first keyword describes how to draw the top, middle, and bottom images, while the second describes the left and right borders. If the second is absent, it is assumed to be the same as the first. If both are absent, the default value<code> stretch </code>is used.</dd>
</dl>
<h3>Examples</h3>
<p>[needs some instructive live examples]</p>
<pre>#header  { -moz-border-image: url(border.png) 27 27 27 27 round round; } 

.button  { -moz-border-image: url(button.png) 0 5 0 5; }

.example { -moz-border-image: url(example.jpg) 3 4 6 8 / 10px 12px 14px 22px; }
</pre>
<pre>/* Edge case, acts like a full scaled background-image in Firefox 3.5 */

 div     { -moz-border-image: url(bgimage.png) 0; } 
</pre>
<h3>Browser compatibility</h3>
<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>
<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>{{ CompatNo() }}<br> {{ unimplemented_inline("497995") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> <tr> <td><code>fill</code> keyword</td> <td>{{ CompatNo() }}</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>
<h4>Notes</h4>
<ul> <li>Unusually, for Opera, the prefixed property was added <em>after</em> the non-prefixed.</li>
</ul>
<h3>Specifications</h3>
<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