CSS border-image-width Property

This property defines the thickness of the boundary where the border image is drawn, essentially setting the frame width for your custom graphics.

selector { border-image-width: value; }
<length> Defines the width of the border image area using specific units like px, em, or rem.
<percentage> Sets the width as a percentage of the border image area's dimensions.
<number> Acts as a multiplier for the element's computed border-width property.
auto Forces the border image width to match the intrinsic size of the image slice.

Code Examples

A basic example showing how to apply a fixed pixel width to a border image.

<div style="border: 20px solid #cccccc; border-image-source: url('https://www.w3schools.com/cssref/border.png'); border-image-slice: 30; border-image-width: 20px; padding: 20px;">
  This box uses a fixed 20px width for the border image.
</div>

An advanced example using JavaScript to toggle the border-image-width using unitless numbers as multipliers.

<div id="dynamicFrame" style="border: 10px solid #333333; border-image-source: url('https://www.w3schools.com/cssref/border.png'); border-image-slice: 30; border-image-width: 1; padding: 20px;">
  Click the button to double the image border thickness.
</div>
<button onclick="toggleWidth()">Toggle Thickness</button>

<script>
function toggleWidth() {
  const box = document.getElementById("dynamicFrame");
  // Using number values as multipliers of the border-width
  if (box.style.borderImageWidth === "1") {
    box.style.borderImageWidth = "3";
  } else {
    box.style.borderImageWidth = "1";
  }
}
</script>

Pro Tip

If you want your border image to look exactly like the source graphic without doing any math, use the auto value. This tells the browser to respect the original dimensions of the image slices, ensuring a pixel-perfect render every time.

Deep Dive

Think of border-image-width as the canvas area reserved for your border image. It is important to realize this property does not actually create a border or affect the box model layout; it only specifies how far the image slices extend into the element. If you set this value larger than the actual border-width, the image will simply overlap your padding and content. You can provide one, two, three, or four values to control the top, right, bottom, and left sides independently, following the standard CSS clock-face order.

Best Practices

Always define a standard border-style and border-width first so there is a fallback for older browsers or if the image fails to load. Using unitless numbers is often the best approach because it scales the image thickness proportionally to the element's border-width, making your design more maintainable if you decide to change the border size later.

Common Pitfalls

A common mistake is thinking this property changes the size of the element itself. It doesn't. If your border image looks stretched or pixelated, it's usually because the border-image-width doesn't match the dimensions of your source image slices or the border-image-slice values.

Accessibility

Since this property is purely visual and decorative, it has no direct impact on accessibility for screen readers. However, you should ensure that any content inside the element remains legible even if the border image overflows into the content area due to a large width setting.

Dev Data Table: border-image-width property

default 1
animatable yes
inherited no
experimental no
year_intro 1999
year_standard 2011
js_syntax_1 element.style.borderImageWidth = "20px";
js_syntax_2 element.style.setProperty("border-image-width", "2");
js_note When using JavaScript, property names are camelCased and the value must be passed as a string encapsulated in quotes.
browsers { "Chrome": 15, "Edge": 12, "Firefox": 13, "Safari": 6, "Opera": 15, "Chrome Android": 18, "Safari on iOS": 6, "Samsung Internet": 1, "Opera Mobile": 14 }
results render here...