Border-image-width - CSS Property

Syntax diagram of border-image-width.

In the diagram, the bold terms are the predefined words of CSS, the other terms are described below:

• lengthis a numeric value followed by one of CSS dimension units.
• % is a percentage calculated relative to the size of the border-image area (which is most often the size of the element, unless border-image-outset has a value other than 0.}.
• number is a number without a unit.
• This syntax can be repeated from one to four times.

Description of the border-image-width property.

border-image-width} sets the width of the border-image. Besides, it enlarges or shrinks the images to fit within this thickness.

For a general overview of images in borders, see the shorthand property border-image. And to set the thickness of a regular (non-image) border, see the border-width property.

Other properties related to image borders.

Values for border-image-width.

In the examples below, the image used for the border measures 45 pixels on each side. border-image-slice is set to the value 15.


• border-image-width: auto;

  Value automatically determined based on the value of border-image-slice. In our examples, this property is 15.

  border-image-width:auto;
  On an image

  border-image-width:auto;
  On a gradient without dimensions.
• border-image-width: 15px;

  From one to four values expressed with a unit of measurement (see CSS dimension units), they define the thickness of the border image.

  border-image-width:5px;
• border-image-width: 1;

  One to four without unit values indicate a multiple relative to the border-width. Don't confuse border-width, which is the thickness of the standard border, with border-image-width, which is the thickness of the border-image.

  The default value is 1, which gives an image border the same width as a normal border.

  border-image-width:2;
border-width:5px;
• border-image-width: 10%;

  From one to four values expressed as a percentage. The percentages are calculated relative to the size of the border area, which is usually the same as that of the element, unless border-image-outset has a value different from zero.

  border-image-width:20%;
• border-image-width: 10px 15px 10px 20px;

  When several values are given, separated by spaces, they set the thickness of each of the border images, following the usual CSS rules:

  If only one value is specified, it applies to all borders.
  
  

  If two values are specified, the first one handles the top and bottom edges, and the second one handles the left and right edges.
  

  When three values are specified, they are assigned to the edges according to the diagram below.
  

  Finally, when four values are given, they take care of the top, right, bottom, and left edges respectively.
  
  border-image-width:5px 15px;
• border-image-width: initial; (1) border-image-width: inherit; border-image-width: revert; border-image-width: revert-layer; border-image-width: revert-rule; border-image-width: unset;

  See the following pages for more details: initial, inherit, revert, revert-layer, revert-rule, unset.

Animation of the border-image-width property.

The property border-image-width can be easily animated. You just need to be careful not to mix unitless values with values that have units (pixels, percentages, etc.) in the @keyframes rule. This is especially critical when you have a zero value, which must explicitly include the unit (whereas normally, you can omit it).

Access the border-image-width property via a program

Change the thickness of a border-image with Javascript.

Two variants of JavaScript code to change the value of border-image-width. The value can be specified exactly like in CSS: in pixels, percentages, or any other unit of measurement.

let el = document.getElementById('id'); el.style['border-image-width'] = '1cm'; // or let el = document.getElementById('id'); el.style.borderImageWidth = '1cm';

Read the thickness of an border-image with Javascript.

The code below reads back the value of the border-image-width property that was set directly through the style attribute of the element (so in the HTML code). Values set in the style-sheet via a CSS selector are not taken into account.

let el = document.getElementById('id'); let value = el.style['border-image-width']; // or let el = document.getElementById('id'); let value = el.style.borderImageWidth;

Read the computed thickness of the border-image in JavaScript.

The computed value is the one that comes from resolving the inheritance cascade. If not, the computed value is the initial value of the property (1 in the case of border-image-width).

The value is converted into pixels, no matter what unit was used to define it. However, percentages are kept as they are.

let el = document.getElementById('id'); let value = window.getComputedStyle(el).getPropertyValue('border-image-width');

With JQuery, read or change the value of border-image-width.

Just like in JavaScript, there’s a syntax with the property name written in camel-case (borderImageWidth) and another syntax with a kebab-case notation.


// Read the value:
$('#id').prop('border-image-width');
// Write the value:
$('#id').prop('border-image-width', '1cm');
$('#id').prop('{border-image-width': '1cm'});


With JQuery, read the computed value of border-image-width.

Like in JavaScript, the value is returned in pixels or percentages.

let value = $('#id').css('border-image-width');

Other examples.

Find more examples on the Javascript and CSS page.

Test it yourself.

The buttons below apply the entered value to the border-image-width property and then display either the value as it was applied or the computed value. This second option lets you see how the value of border-image-width is stored (serialized). In particular, you'll notice that percentages are correctly stored as percentages. All other units are converted into pixels.

Simulator.

This simulator lets you choose the value of the border-image-width property, with the border-image-slice and border-image-source properties having been set to 10 and a radial gradient, respectively.

Browsers compatibility with border-image-width.

The property border-image-width, as well as all properties related to border images, have been supported from 2015 to 2017 depending on the browsers.

Notes:

(1) Supports the summary property but not detailed properties.
Doesn't support the space and round values

1

Using images
for borders

2

border-image-width
property

Estimated overall support.

97%

96%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

KaiOS Browser

Opéra Mobile

Chrome

Edge

Opéra

Safari

Safari sur IOS

Androïd Brower

Chrome pour Androïd

Firefox pour Androïd

Samsung Internet

Firefox

Baidu Browser

QQ Browser

UC Browser pour Androïd

Opéra mini

1

See Caniuse.com for more compatibility information.

Caniuse

Caniuse

Historic of the border-image-width property.

• CSS Backgrounds and Borders Module Level 3

  Level 3 of the specification also explains how to position the background relative to the background area, and how to crop it.
  Regarding borders, the concept of image borders is introduced, as well as the ideas of rounded corners and box shadows.

  Regarding border-image-width Introduction of borders made with an image, instead of simple paths.
  First definition of the border-image-width property.
  

  August 02, 2002

  Working Draft.

  

  December 17, 2009

  Candidate Recommendation.

  

  

See also: other features of borders and backgrounds.

The properties related to borders and backgrounds are described in the W3C specification called CSS Backgrounds and Borders Module. Here is the list:

Properties: