CSS border-image-width Property

Beginner
6 min read
Updated: Oct 2026
3 examples
Live preview
CSS border-image-width controlling how thick a border image is painted
Definition

Definition and Usage

The border-image-width property sets how thick the border image is drawn on each side. It is separate from border-width, which reserves space in the box model.

The initial value is 1 (a multiple of border-width). If the image width is larger than border-width, the painted frame can overlap padding or content. Negative values are invalid.

Baseline · Widely available.

Not deprecated and not experimental. Available across browsers since July 2015. Needs a border-image-source and slice to show any effect.

Syntax

CSS Syntax

syntax.css
border-image-width: <length-percentage> | <number> | auto | initial | inherit;

Use one to four values, like margin. Example: border-image-width: 20px 40px; for top/bottom then left/right.

Values

Property Values

ValueDescriptionTry it
<length>Fixed paint thickness, such as 20px or 1remTry it
<percentage>Relative to the border image area (width for horizontal, height for vertical)Try it
<number>Multiple of that side’s border-width. Default is 1Try it
autoUses the intrinsic size of the matching border-image-sliceTry it
Two valuesFirst is top and bottom; second is left and rightTry it
initialResets to the default value, 1Try it
inheritInherits this property from the parent elementTry it
Approach

How to Use border-image-width

Set up a border image first, then choose how thick that image should paint.

  1. Set a non-zero border-width (for example border: 10px solid;).
  2. Add a border-image-source and border-image-slice.
  3. Set border-image-width to a length, number, percentage, or auto. It is not inherited.
  4. Remember: a paint width larger than border-width can overlap the inside of the box.
PieceRequired?Role
border-widthYesBox-model space; also the base for number multipliers
Source + sliceYesThe artwork that gets painted at the chosen width
Image widthOptionalDefaults to 1 (same as border-width)
ClearanceOftenExtra padding if the image paints wider than the border
Try it

Live Preview

The box has a fixed border-width: 10px. Change border-image-width and watch the painted frame grow or shrink.

border-width stays 10px. Number values multiply that width (2 means 20px of paint).

Width

border-image-width: 20px

Code

CSS Examples

Each snippet adds only what border-image-width needs: a border, a source, a slice, and a width value. Use Try It Yourself for a live editor.

Example 1 — Length Width

Paint the border image at a fixed 20px, even if border-width is smaller.

CSS
<style>
  div {
    border: 10px solid;
    border-image-source: url("/images/apple.png");
    border-image-slice: 30;
    border-image-width: 20px;
    padding: 12px;
  }
</style>

<div>20px image width</div>
Try It Yourself

How It Works

  1. Reserve 10px of border space. That is the box-model border-width.
  2. Load and slice the source. Source and slice set up the artwork.
  3. Paint at 20px. border-image-width: 20px draws the frame thicker than the reserved border.
  4. Overlap inward. Because 20px > 10px, the image extends past the border edge into the padding area.

Example 2 — Number Multiplier

Use a unitless number so the paint width scales with border-width.

CSS
<style>
  div {
    border: 10px solid;
    border-image-source: url("/images/apple.png");
    border-image-slice: 30;
    border-image-width: 2;
    padding: 12px;
  }
</style>

<div>2 × border-width</div>
Try It Yourself

How It Works

  1. Keep a 10px border. That value is the base for the multiplier.
  2. Set width to 2. 2 means 2 × 10px = 20px of painted image on each side.
  3. Default is 1. Omitting the property (or using 1) paints at exactly border-width.
  4. Scale together. Change the border width later and the image width follows automatically.

Example 3 — Auto

Size the paint from the intrinsic size of each border-image slice.

CSS
<style>
  div {
    border: 10px solid;
    border-image-source: url("/images/apple.png");
    border-image-slice: 30;
    border-image-width: auto;
    padding: 12px;
  }
</style>

<div>auto width</div>
Try It Yourself

How It Works

  1. Same source and slice. The slice regions still come from the image.
  2. Choose auto. Each side’s paint width follows the intrinsic size of that slice.
  3. Fallback. If a side has no intrinsic size, the browser uses that side’s border-width instead.
  4. Good for artwork. Useful when the slice size in the file should drive the painted thickness.

Edge Cases & Pitfalls

If the frame looks too thin, too thick, or covers text, check these first.

vs

Not the same as border-width

border-width reserves layout space. border-image-width only controls how large the image paints.

overlap

Larger than border-width overlaps inward

If the image width exceeds border-width, the paint can cover padding or content. Add padding when that happens.

source

No source, no visible width

You still need a border-image-source and slice. Width alone does not create a frame.

number

Numbers multiply border-width

With border-width: 10px, border-image-width: 2 paints at 20px. The default 1 matches the border exactly.

reset

border resets the image

The border shorthand sets border-image back to none. Declare source, slice, and width after border.

Compatibility

Browser Support

border-image-width is a browser CSS property for decorative borders. Node.js, Deno, and Bun do not apply it.

✓ Baseline · Widely available

border-image-width

Chrome 15+, Firefox 13+, Safari 6+, Edge 12+, Internet Explorer 11+. The auto keyword is supported from Chrome 16+.

97% Global support
Google Chrome 15+ · auto 16+
Full support
Mozilla Firefox 13+
Full support
Apple Safari 6+
Full support
Microsoft Edge 12+
Full support
Opera 15+
Full support
Samsung Internet 1.0+
Full support
Internet Explorer 11
Full support
border-image-width Widely supported

Bottom line: Safe for production. Prefer a length or number when you want predictable thickness; use auto when the slice size should drive the paint. It is not a runtime API.

Remember

Key Takeaways

  • Role: how thick the border image paints on each side.
  • Default: 1 (matches border-width). Not inherited.
  • Not box model: larger paint can overlap padding or content.
  • Values: length, percentage, number multiplier, or auto.

One line: border-image-width sets the paint thickness of the frame — after you have a source and slice, and separately from border-width.

Frequently Asked Questions

It sets how thick the border image is drawn on each side. It can use a length, a percentage, a unitless multiple of border-width, or auto.
The initial value is 1, a unitless number. That makes the painted image width match the element’s border-width on each side.
border-width reserves space in the box model. border-image-width controls how large the sliced image is painted. If the image width is larger than border-width, the image can overlap padding or content.
auto uses the intrinsic size of the matching border-image-slice. If the source has no intrinsic size for that side, the browser falls back to border-width.
Yes. Use one to four values like margin: one for all sides; two for top/bottom then left/right; four for top, right, bottom, left.
It is Baseline Widely available: Chrome 15+, Firefox 13+, Safari 6+, Edge 12+, and Internet Explorer 11. The auto keyword is supported from Chrome 16+. It is a browser CSS property, not a Node.js feature.

Next: border-inline

Set the logical inline-start and inline-end borders in one declaration.

border-inline tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

CSS border-image-source Property CSS border-inline Property