border-image-slice | CSS-Tricks

CSS Almanac → Properties → B → border-image-slice

Sunkanmi Fafowora on Dec 20, 2022

The CSS border-image-slice tells the browser where to “slice” an image being used to create the pieces of an element’s borders.

.element {
  border-style: ridge;
  border-width: 3rem;
  border-image-source: url('path/to/image.jpg');
  border-image-slice: 30%;
  border-image-repeat: repeat; 
}

The border-image-slice property is defined in the CSS Backgrounds and Borders Module Level 3 specification.

When the border image is sliced, it is divided into nine sections — the four corners, the four sides, and the middle — by drawing four invisible slice lines over the image that form regions sort of like a grid. The property values offset that grid of slice lines from the image’s respective sides.

Areas 1-4 represent the four corner regions.
Areas 5-8 represent the four side regions.
Area 9 represents the middle region.

Demo

Adjust the border-image-slice values in the following demo to see how the image offsets at different lengths or percentages.

Syntax

border-image-slice: [<number [0,∞]> | <percentage [0,∞]>]{1,4} && fill?

Initial value: 100%
Applies to: all elements (including the ::first-letter pseudo-element), except internal table elements when border-collapse is set to collapse.
Inherited: no
Percentages: relative to the size of the source image
Computed value: one to four values, each either a number or percentage; plus a fill keyword, if specified
Animation type: by computed value

border-image-slice accepts between one and four values that set where the border image is sliced along each value’s corresponding side.

One value: Sets all four sides — top, right, bottom, and left — at the same offset distance.
Two values: The first value sets the offset for the top and bottom sides; the second value sides the offset for the left and right sides.
Three values: The first value sets the offset for the top side; the second value sets the offset for the right and left sides; the third sets the offset for the bottom side.
Four values: Sets the offset for each side in clockwise order, starting from the top side — top, right, left, and bottom, respectively.

Values

/* Single value */
/* Sets all four sides */
border-image-slice: 20; 
border-image-slice: 30%;

/* Two values */
/* top and bottom | right and left */
border-image-slice: 30% 20;
border-image-slice: 10% 30%;
border-image-slice: 20% 10%;

/* Three values */
/* top | left and right | bottom */
border-image-slice: 40 31 11;
border-image-slice: 12 41 15;
border-image-slice: 10% 30% 5%;

/* Four values */
/* top | right | bottom | left */
border-image-slice: 15% 20 10% 10;
border-image-slice: 10 30 40 10;
border-image-slice: 15% 20 10% 40;

/* Optional `fill` value */
border-image-slice: 10 fill;
border-image-slice: 30% 20 fill;
border-image-slice: 40 31 11 fill;
border-image-slice: 10 30 40 10 fill;

/* Global values */
border-image-slice: inherit;
border-image-slice: initial;
border-image-slice: revert;
border-image-slice: revert-layer;
border-image-slice: unset;

`number [0,∞]`

This represents a length value in pixels from zero to infinity, if the border image is a raster image. If the border image is a vecor-based image — such as SVG — with no natural dimensions, the number is based on the vector coordinates.

The following demo is an example of a raster image where the border-image-slice property is set to 125, resulting in slices that are offset by 125px.

A few things to bear in mind when working with length values:

Negative values are not allowed.
Values that are larger than the size of the image compute to 100%.
If the sum of the left and right sides are greater than the width of the image, then the top, bottom, and middle areas are blank as though a transparent image were used. Same goes for situations where the sum of the top and bottom values is greater than the image height — the left, right, and middle areas will be blank.

`percentage [0,∞]`

Percentages are relative to the size of the border image. For example, a border-image-slice: 50% is equal to 100px when set on a 200px-square image.

The following demo is an example of a 740px × 493px raster image where the border-image-slice property is set to 10%, resulting in slices that are offset by 74px (740px * 10%) along the top and bottom sides and 49.3px (493px * 10%) along the left and right sides.

`fill` (optional)

The fill value for the CSS border-image-slice acts like a background image for the middle region, filling it with the border image you provide it. It is an optional value that completely ignores the number constraint for the maximum number of values border-image-slice can take. This means that if all four values are set for the top, right, bottom, and left borders, we can set fill as a fifth value that fills the middle part of the element with the border image.

.container {
  /* top | right | bottom | left | middle */
  border-image-slice: 78 65 70 75 fill;
}

And it doesn’t even matter where we put fill in the declaration — any order works!

.container {
  /* This is valid too! */
  border-image-slice: 78 65 fill 70 75;
}

In the following example, the fill keyword is used to apply the border image to the element’s middle region:

For the fill value to work, you must first set at at least one value on the border-image-slice property. Without that, nothing is shown in the middle region.