CSS text-box playground

Educational guide to text-box

Align text using its font metrics

A centered box does not always look centered. Learn to adjust the outer space of a line with text-box-trim and text-box-edge, keeping readable line spacing and room for every character.

Back to the playground

Mental model

font-size defines the reference size of the font. Letter ink, font metrics and the line box occupy different spaces.

From the line box to font metricsConceptual diagram of a horizontal line, without actual measurements. Positions illustrate relationships; metrics and ink vary with each font.

1 · Line boxline-height contributes to line spacing; its boundaries are not the boundaries of the ink.
2 · Capital height · capThe font reference for letters such as H; an accent can extend higher.
3 · x-height · exThe font reference for lowercase letters such as x; it does not enclose every letter.
4 · Baseline · alphabeticThe resting line for many letters. Descenders in g or y can extend below it.

text-box adjusts box edges using font metrics. It can remove space from leading and font metrics above and below the text. It does not change character shapes or sizes, and it does not measure the exact outline of each word.

Which edge to trim and how far

The trimming direction and the target metric are independent choices.

text-box-trim chooses the edges: none leaves them unchanged, trim-start trims the block start, trim-end trims the block end and trim-both trims both. In the horizontal writing mode of these scenes, these are top and bottom; they are block directions, not universal physical sides.

text-box-edge chooses the references. cap alphabetic combines capital height and baseline; ex alphabetic uses x-height and baseline. text preserves the font ascent and descent references. cap text or ex text keeps the lower text reference; text alphabetic keeps the upper text reference.

Choosing a metric with text-box-edge does not activate trimming while text-box-trim remains none. auto is the initial edge value; use an explicit pair to express the alignment intent of a recipe. The following syntaxes produce the same trimming.

text-box: trim-both cap alphabetic;

text-box-trim: trim-both;
text-box-edge: cap alphabetic;

Apply the property to the element containing the text. A flex or grid container does not pass trimming through to its items: for a label with an icon, wrap the text in a span and trim that span. Keep padding and target size on the outer control.

Alignment with an icon

align-items centers boxes. When the text box includes extra space, its ink may look offset relative to the icon.

The same label, with and without trimming

No trimming · none

BASELINE

Trimmed · cap alphabetic

BASELINE

Both labels have the same font, line height and padding. Dashed lines mark the span edges: the second trims them to cap and alphabetic when the browser supports that declaration. The circle is decorative; these samples are not buttons.

The same label, with and without trimming

HTML

<div class="text-box-guide-badges">
  <div>
    <p>No trimming · none</p>
    <div class="text-box-guide-badge">
      <span aria-hidden="true">●</span>
      <span class="text-box-guide-label">BASELINE</span>
    </div>
  </div>
  <div>
    <p>Trimmed · cap alphabetic</p>
    <div class="text-box-guide-badge">
      <span aria-hidden="true">●</span>
      <span class="text-box-guide-label is-trimmed">BASELINE</span>
    </div>
  </div>
</div>

CSS

:root {
  color-scheme: light dark;
}

.text-box-guide-badges {
  display: flex;
  flex-wrap: wrap;
  gap: 2rem;
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));

  p {
    margin: 0 0 1rem;
    font: 1rem/1.5 system-ui, sans-serif;
  }
}

.text-box-guide-badge {
  display: inline-flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 0.75rem;
  padding: 1rem;
  border: 1px solid light-dark(oklch(0.84 0.01 95), oklch(0.36 0.024 260));
  border-radius: 16px;
  background: light-dark(color-mix(in oklch, oklch(0.95 0.008 95) 98%, white), color-mix(in oklch, oklch(0.22 0.024 260) 86%, black));
  font: 700 1.5rem/1.6 system-ui, sans-serif;
}

.text-box-guide-label {
  border-block: 1px dashed light-dark(oklch(0.46 0.14 261), oklch(0.82 0.18 261));

  &.is-trimmed {
    text-box: trim-both cap alphabetic;
  }
}

cap alphabetic is a useful reference for uppercase labels, but does not guarantee optical centering for every word. Weight, icon shape, lowercase letters and accents affect the result. Evaluate real text without numeric corrections tied to a single font.

Line height and multiline text

Space between lines and outer block space serve different purposes.

In a block, trim-start trims the first line and trim-end the last line. Space between internal lines still depends on line-height. Do not replace comfortable line spacing with line-height: 1 just to remove outer space from a heading.

Two lines with line-height: 1.8

No trimming · none

Design with
real metrics

Trimmed · cap alphabetic

Design with
real metrics

The explicit break keeps two comparable lines. The second block trims its outer edges while retaining the distance between lines. Text may wrap further on a narrow screen; trimming still applies to the actual first and last lines.

Two lines with line-height: 1.8

HTML

<div class="text-box-guide-lines">
  <div>
    <p class="text-box-guide-caption">No trimming · none</p>
    <p class="text-box-guide-heading">Design with<br>real metrics</p>
  </div>
  <div>
    <p class="text-box-guide-caption">Trimmed · cap alphabetic</p>
    <p class="text-box-guide-heading is-trimmed">Design with<br>real metrics</p>
  </div>
</div>

CSS

:root {
  color-scheme: light dark;
}

.text-box-guide-lines {
  display: grid;
  gap: 2rem;
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
}

.text-box-guide-caption {
  margin: 0 0 1rem;
  font: 1rem/1.5 system-ui, sans-serif;
}

.text-box-guide-heading {
  margin: 0;
  border-block: 2px solid light-dark(oklch(0.46 0.14 261), oklch(0.82 0.18 261));
  font: 700 1.5rem/1.8 system-ui, sans-serif;
  overflow-wrap: anywhere;

  &.is-trimmed {
    text-box: trim-both cap alphabetic;
  }
}

margin, padding and border remain present: text-box does not remove them. It can help align a heading edge with an image; for long paragraphs, prioritize readability and vertical rhythm. Allow content to grow when text is enlarged.

Fonts, accents and descenders

The same metric pair expresses a common intent, not identical heights across fonts.

system-ui, serif and monospace resolve to different fonts depending on the device. Each has its own capital height, x-height and descenders. A web font and its fallback can also produce different boxes during loading; check both states.

cap and ex with three font families

system-ui · cap / ex

ÁHxgy ÁHxgy

serif · cap / ex

ÁHxgy ÁHxgy

monospace · cap / ex

ÁHxgy ÁHxgy

In each row, the first sample uses cap alphabetic and the second ex alphabetic. Observe Á, H, x, g and y against the borders: ink can extend beyond them. Actual fonts depend on the system; this example does not download fonts or promise constant measurements.

cap and ex with three font families

HTML

<div class="text-box-guide-fonts">
  <div>
    <p>system-ui · cap / ex</p>
    <div class="text-box-guide-samples">
      <span class="text-box-guide-font">ÁHxgy</span>
      <span class="text-box-guide-font is-ex">ÁHxgy</span>
    </div>
  </div>
  <div>
    <p>serif · cap / ex</p>
    <div class="text-box-guide-samples">
      <span class="text-box-guide-font is-serif">ÁHxgy</span>
      <span class="text-box-guide-font is-serif is-ex">ÁHxgy</span>
    </div>
  </div>
  <div>
    <p>monospace · cap / ex</p>
    <div class="text-box-guide-samples">
      <span class="text-box-guide-font is-mono">ÁHxgy</span>
      <span class="text-box-guide-font is-mono is-ex">ÁHxgy</span>
    </div>
  </div>
</div>

CSS

:root {
  color-scheme: light dark;
}

.text-box-guide-fonts {
  display: grid;
  gap: 2rem;
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));

  p {
    margin: 0 0 1rem;
    font: 1rem/1.5 system-ui, sans-serif;
  }
}

.text-box-guide-samples {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 2rem;
  padding-block: 1rem;
}

.text-box-guide-font {
  display: block;
  border-block: 2px solid light-dark(oklch(0.46 0.14 261), oklch(0.82 0.18 261));
  font: 700 2rem/1.6 system-ui, sans-serif;
  text-box: trim-both cap alphabetic;

  &.is-serif {
    font-family: serif;
  }

  &.is-mono {
    font-family: monospace;
  }

  &.is-ex {
    text-box-edge: ex alphabetic;
  }
}

Trimming the box does not itself clip the ink. An accent may extend above cap; an uppercase letter may extend above ex; g or y may extend below alphabetic. overflow: hidden or clip and a fixed height can hide that ink. Leave room and test real languages, fonts, zoom and focus.

For uppercase labels, start with cap alphabetic. ex alphabetic can help align lowercase letters but needs room for ascenders and accents. text provides a broader font reference; no pair replaces reviewing the actual content you will use.

Explore font-size-adjust and fallback fonts

Common mistakes

Check the box, metric and formatting context before adding offsets.

Changing edge makes no difference

Expected result: Trim the box to capital height.
Cause: text-box-trim is none, or the browser does not support the specific declaration.
Solution: Enable trim-both and check the complete pair with @supports or CSS.supports().

The icon and text remain misaligned

Expected result: Center the label using text metrics.
Cause: Trimming is on the flex container, outside the box containing the text.
Solution: Wrap the text in a span and apply text-box there; keep align-items on the container.

Accents or descenders disappear

Expected result: Keep every character while making the box more compact.
Cause: Ink extends beyond the chosen metric and an ancestor uses clipping or a fixed height.
Solution: Remove unnecessary clipping, allow automatic height and leave sufficient space.

Heading lines become too close together

Expected result: Remove outer space without making reading harder.
Cause: line-height was reduced to solve a problem at the block edges.
Solution: Restore readable line spacing and use text-box only to trim the outer edges.

Support and compatibility

Trimming is a visual enhancement. Text and the base layout must also work without it.

Check the complete declaration, not just whether text-box exists. The shorthand, longhands and text-box-edge values may have different support. Draft ideographic and ideographic-ink values have their own compatibility and are not used in these recipes.

If the browser ignores text-box, samples retain their font, line height and conventional spacing. Trimmed and untrimmed pairs may look identical. The enhancement is not simulated with negative margins, and no essential action depends on an exact height.

@supports (text-box: trim-both cap alphabetic) {
  .label { text-box: trim-both cap alphabetic; }
}

@supports lets you isolate an enhancement by its syntax. It does not certify visual results, interoperability or enough room for every character. Check the result with your target fonts and browsers.