CSS Reference Property

border-image-width

The border-image-width property is used to scale the border-image slices created by the border-image-slice property.

The border image width will tell the browser how wide each border side is so that it can scale the border image to fit in it.

The area inside which the border image is to be painted is called the border image area. By default, the boundaries of the border image area correspond to the boundaries of the element’s border box. (However, the boundaries of the border image area can be extended using the border-image-outset property.)

The border-image-width is specified as a list of offsets from the boundaries of the border image area.

offsets-slices
The four lines represent virtual lines that show the corresponding offsets for the border image area inwards from the element’s border image area (which in this case is the border box because no border image outset has been set).

The border-image-width property can take four, three, two, or one offset values.

When four values are specified, they set the offsets on the top, right, bottom and left sides in that order. If three values are specified, the first one specifies the top offset, the second one specifies the right and left offsets, and the third one specifies the bottom offset. If two values are specified, the first one specifies the top and bottom offsets, and the second one specifies the right and left offsets. If one value is specified, it specifies all the four offsets.

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.

The offsets specified by the border-image-width property are then used to scale the slices of the border image obtained from the border-image-slice property.

The top and bottom edge (Edge 1 and Edge 3) are scaled so that their height matches the top and bottom offsets of the border-image-width, and their width is scaled proportionally. The right and left edges (Edge 2 and Edge 4) are scaled so that their width matches that specified by the right and left offsets of the border-image-width, and their height is scaled proportionally.

The width of the top and bottom edges, and the height of the right and left edges then rescaled in a next step based on the value of the border-image-repeat property.
You can read more about how these properties work together in the border-image shorthand property entry.

The height and width of the border image corners (corners 1 through 4 in the above image) is determined by scaling the corners to the offsets of the edges that they are part of. For example, the top right corner slice, will be scaled so that its width matches the right offset of the border-image-width and its height matches the top offset provided by the border-image-width property.

As for the middle slice of the border image, is it either discarded or preserved, depending on whether the fill value is present in the border-image-slice property. If it is preserved, its width is scaled by the same factor as the top image edge 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 edge 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.

Notes and Trivia

A lot of resources may tell you that you must or should specify the same border image width offsets as the border-image-slice offsets. You don’t have to do that, but sometimes, depending on the border image you’re using and the effect you’re after, it may be simpler to do so.

Official Syntax

Values

The informal syntax looks something like this:

border-image-width = [offset] [offset]? [offset]? [offset]?
                

The question mark (?) indicates that the value is optional. When one offset is specified, it is used as a top, right, bottom, and left offset. When two offsets are specified, the first one represents the top and bottom offsets and the second one represents the right and left offsets. When three offsets are specified, the first represents the offset from the top, the second one represents the offset from the right and left, and the third one represents the bottom offset. When four offsets are specified, they represent the top, right, bottom, and left offsets, in that order.

These offsets can be specified as <length>, <number>, or <percentage> values. Negative offset values are not allowed for any of the border-image-width values.

<length>
See the <length> entry for a list of possible values.
<percentage>
Percentages refer to the size of the border image area: the width of the area for horizontal offsets, the height for vertical offsets.
<number>
A <number> value represents multiples of the corresponding computed border-width of the element.
auto

If auto is specified then the border image width is the intrinsic width or height (whichever is applicable) of the corresponding image slice (see border-image-slice). If the image does not have the required intrinsic dimension then the corresponding border-width is used instead.

So, auto leaves it up to the browser to determine the border image width depending on whether the image slices have an intrinsic width or not. If they don’t have an intrinsic width, the value of the border-width is used.

Notes

The border-image-width can also inherit its values from the computed values of the element’s parent, using the inherit keyword.

Examples

The following are valid border-image-width declarations:

border-image-width: 30px; /* one-value syntax, all offsets will be equal to 30px */
border-image-width: 10% 30%; /* two-value syntax, top and bottom offsets = 10%, right and left offsets = 20% */
border-image-width: auto; /* specify offset based on the slice intrinsic width */
border-image-width: auto 30px; 
border-image-width: 10px 20px 30px 25px;
border-image-width: 4; /* border image width is 4 times the width of the border specified using the boder-width property */
                

Live Demo

The border image used is the following:
border-img
It is 81px in width and 81px in height. Each rhombus is 27px in width and 27px in height. The border image width is set to 27px as well, so the image slices’ proportions are not scaled or changed. Play with the value of the border-image-width property to see how that affects the scale of the image parts.

View this demo on the Codrops Playground

Browser Support

CSS3 Border images

Method of using images for borders

W3C Candidate Recommendation

Supported from the following versions:

Desktop

  • 4*
  • 3.5*
  • 11
  • 10
  • 3.1*

Mobile / Tablet

  • 3.2*
  • 2.1*
  • 11*
  • 56
  • 51

* denotes prefix required.

  • Supported:
  • Yes
  • No
  • Partially
  • Polyfill

Stats from caniuse.com

Written by

Last updated December 11, 2016 at 10:19 pm by Mary Lou

Do you have a suggestion, question or want to contribute? Submit an issue.