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.
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
-
Syntax:
border-image-width: [<length> | <number> | <percentage> | auto]{1,4}
- Initial: 1
-
Applies To: All elements, except internal table elements when
border-collapseiscollapse - Animatable: no
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 computedborder-widthof the element. - auto
-
If
autois specified then the border image width is the intrinsic width or height (whichever is applicable) of the corresponding image slice (seeborder-image-slice). If the image does not have the required intrinsic dimension then the correspondingborder-widthis used instead.So,
autoleaves 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 theborder-widthis 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:
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.
Browser Support
CSS3 Border images
Method of using images for borders
W3C Candidate Recommendation
Supported from the following versions:
Desktop
- 56
- 50
- 11
- 43
- 15
Mobile / Tablet
- 15
- 131
- No
- 131
- 132
