CSS transform-box Property

Description

The transform-box CSS property selects which geometric rectangle is used as the reference for applying transforms to an element. In practical terms, it determines the coordinate box that translation, rotation, scaling and other transform operations are measured against, which can change the apparent pivot, scale origin and clipping extents of the transformed content. This is particularly important when working with drawn graphics (for example, SVG shapes) and replaced elements where there are multiple sensible boxes (visual bounding box, geometric content box, or the element’s viewport), because choosing a different reference box can produce markedly different visual results from the same transform.

Because it changes the frame of reference, transform-box directly affects how the transform functions behave: the same transform matrix applied to two different boxes will move and resize pixels into different places. It also modifies how the anchor point set by transform-origin is interpreted — the origin coordinates are resolved relative to the selected box, so rotating or scaling an element can appear to pivot around a different spot depending on which box is chosen. For vector graphics, the property also influences whether strokes and fills are included in the measured bounds used for transformations, which changes visual outcomes when you are animating or aligning graphics precisely.

The property impacts compositing and nested transforms as well. When elements are transformed inside a hierarchy, the chosen reference box can alter how child transforms compose with parent transforms and whether a child’s transform is perceived as local or offset; this interacts with 3D composition behavior governed by transform-style. Although changing the reference box does not change document flow (transforms are still applied after layout), it can change visual overlap, clipping and how hit-testing appears to the user because the transformed geometry ends up in a different position and extent on the final painting surface.

In practice, you adjust transform-box when you need predictable, repeatable transform behavior across different kinds of content (HTML vs SVG, filled shapes vs stroked outlines) or when the default bounding region yields awkward pivots or scaling artifacts. It is a fine-grained control: small adjustments can realign rotation centers, avoid unexpected clipping, or ensure transforms scale the exact portion of the graphic you intend without changing your transform sequences or keyframes.

Definition

Initial value: view-box
Applies to: transformable elements
Inherited: no
Computed value: as specified
Animatable: yes
JavaScript syntax: object.style.transformBox

Syntax

transform-box: content-box | border-box | fill-box | stroke-box | view-box

Values

content-boxThe content box is used as the reference box. The reference box of a <table> is the border box of its table wrapper box, not its table box.
border-boxThe border box is used as the reference box. The reference box of a <table> is the border box of its table wrapper box, not its table box.
fill-boxThe object bounding box is used as the reference box. For elements with associated CSS layout box, acts as content-box.
stroke-boxThe stroke bounding box is used as the reference box. For elements with associated CSS layout box, acts as border-box.
view-boxThe nearest SVG viewport is used as the reference box. If a viewBox attribute is specified for the SVG viewport creating element, the reference box is positioned at the origin of the coordinate system established by the viewBox attribute, and the dimension of the reference box is set to the width and height values of the viewBox attribute.

Example

HTML

<div class="wrapper">

  <div class="card">

    <div class="label">transform-box: view-box</div>

    <svg viewBox="0 0 100 100" class="svg">

      <!-- reference: SVG viewport center -->

      <g class="reference">

        <line x1="0" y1="50" x2="100" y2="50" />

        <line x1="50" y1="0" x2="50" y2="100" />

        <circle cx="50" cy="50" r="2" />

      </g>



      <!-- the yellow rectangle will be rotated around the SVG viewBox center -->

      <rect x="10" y="30" width="30" height="40" class="shape view" />



      <!-- a second rectangle to show different bounding boxes in the same SVG -->

      <rect x="60" y="20" width="30" height="60" class="bg-rect" />

    </svg>

  </div>



  <div class="card">

    <div class="label">transform-box: fill-box</div>

    <svg viewBox="0 0 100 100" class="svg">

      <g class="reference">

        <line x1="0" y1="50" x2="100" y2="50" />

        <line x1="50" y1="0" x2="50" y2="100" />

        <circle cx="50" cy="50" r="2" />

      </g>



      <!-- the yellow rectangle will be rotated around its own bounding box center -->

      <rect x="10" y="30" width="30" height="40" class="shape fill" />



      <rect x="60" y="20" width="30" height="60" class="bg-rect" />

    </svg>

  </div>

</div>

CSS

/* Layout */
body {
  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial;
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 100vh;
  margin: 0;
  background: #f6f8fa;
}

.wrapper {
  display: flex;
  gap: 24px;
  padding: 24px;
}

.card {
  background: #fff;
  border-radius: 8px;
  padding: 16px;
  box-shadow: 0 6px 18px rgba(20, 30, 40, 0.08);
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 12px;
}

.label {
  font-size: 13px;
  color: #333;
}

/* SVG styling */
.svg {
  width: 220px;
  height: 220px;
  overflow: visible;
  background: linear-gradient(180deg, rgba(0,0,0,0.02), transparent);
  border-radius: 6px;
  padding: 8px;
}

.reference line {
  stroke: #e6e9ee;
  stroke-width: 1;
}

.reference circle {
  fill: #666;
  opacity: 0.6;
}

.bg-rect {
  fill: none;
  stroke: #e0e6ef;
  stroke-width: 1.5;
}

.shape {
  fill: #ffcc33;
  stroke: #333;
  stroke-width: 1.5;
  /* center-based transform origin; transform-box decides which box "center" refers to */
  transform-origin: center;
  transition: transform 300ms ease;
}

/* Demonstrate difference between transform-box values */
.shape.view {
  transform-box: view-box; /* transforms use the SVG viewport (viewBox) as reference */
  transform: rotate(25deg);
}

.shape.fill {
  transform-box: fill-box; /* transforms use the element's own bounding box as reference */
  transform: rotate(25deg);
}

/* hover to emphasize the pivot difference */
.card:hover .shape {
  transform: rotate(45deg);
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS transform-box property. Hover over a browser icon to see the version that first introduced support for this CSS property.