CSS border-image and Slicing Explained

The CSS border-image property allows developers to use custom graphics or gradients as element borders instead of conventional solid, dashed, or dotted lines. This article explains what the border-image property is, breaks down its core shorthand components, and details the 9-slice grid system used to divide and scale source images dynamically to fit any container.

What is the border-image Property?

The border-image property is a CSS shorthand that draws an image over an element's border area. Instead of repeating an entire image along an outline or stretching it uniformly, it applies a 9-slice scaling algorithm that keeps decorative corners crisp while adapting the edges to boxes of varying dimensions.

To display a border image, an element must have a defined border style or border width. If border-image fails to load or is unsupported, the standard CSS border properties act as a fallback.

The shorthand brings together five individual properties:

  • border-image-source: The image file path or CSS gradient.
  • border-image-slice: The dimensions defining how the image is sliced into regions.
  • border-image-width: The rendered thickness of the border image.
  • border-image-outset: The distance the border extends beyond the element's border box.
  • border-image-repeat: The behavior used to fill the edges (stretch, repeat, round, or space).

The 9-Slice Grid Mechanism

The core mechanism behind border-image is the 9-slice scaling concept. When you provide an image, the browser divides it into a 3×3 grid comprising nine specific regions:

  1. Four Corners (Top-Left, Top-Right, Bottom-Right, Bottom-Left): These sections remain fixed in their aspect ratio. They are placed directly onto the four corners of the HTML element and do not stretch or repeat along the edges.
  2. Four Edges (Top, Right, Bottom, Left): These sections scale, stretch, or tile along the element's sides to bridge the distance between the fixed corners.
  3. One Center: The middle section can either be discarded completely (making the center transparent) or preserved to act as a background fill for the content area.

How border-image-slice Slices the Image

The border-image-slice property creates the cut lines that form the 9-slice grid. It accepts up to four values representing inward offsets from the edges of the source graphic, following the standard CSS order: top, right, bottom, left.

border-image-slice: 30; /* Applies a 30-unit offset to all four sides */
border-image-slice: 20 35 20 35; /* top right bottom left */

Units for Slicing

  • Raw Numbers: For raster graphics (PNG, JPG, WebP), numbers without units represent raw pixels in the source image (e.g., 30 means 30 source pixels).
  • Percentages: Percentages refer to the relative size of the image (e.g., 25% slices one-quarter inward from each side), which is standard for vector graphics like SVG.
  • The fill Keyword: By default, the central region of the source image is discarded. Adding the fill keyword preserves the middle area and paints it behind the element's content.
border-image-slice: 40 fill;

Controlling the Sliced Border Layout

Once sliced, the graphics are rendered using the remaining sub-properties:

1. Sizing with border-image-width

border-image-width controls the physical display thickness of the border on the page, completely independent of the slice size. It accepts standard CSS length units (px, em), percentages, or unitless multipliers that multiply the element's border-width.

border-image-width: 15px;

2. Position with border-image-outset

By default, the border image sits within the element's designated border area. border-image-outset shifts the border image outward, past the element's padding box and border box, without affecting the surrounding layout flow.

border-image-outset: 5px;

3. Edge Filling with border-image-repeat

border-image-repeat dictates how the four edge slices expand across the perimeter of the box:

  • stretch: Stretches the sliced edge graphic to fill the entire side.
  • repeat: Tiles the edge graphic continuously until the space is covered, clipping the graphic if the space is not an exact multiple.
  • round: Tiles the graphic, but dynamically scales the pattern up or down so only whole slices appear without clipping.
  • space: Tiles the graphic, distributing extra space evenly between repeating slices if they do not fit perfectly.

Complete Shorthand Syntax

The full shorthand syntax combines these controls using forward slashes (/) to separate slices, widths, and outsets:

border-image: source slice / width / outset repeat;

Practical Example

.decorative-card {
  border: 12px solid transparent;
  border-image: url("frame-pattern.png") 36 / 12px / 0 round;
}

In this implementation, the browser loads frame-pattern.png, measures 36 pixels inward from every edge to isolate the corners and edge patterns, draws the border at 12 pixels wide, and tiles the side segments smoothly using the round algorithm.