Trimming Text Box Whitespace: An Introduction to text-box-trim and text-box-edge

When you set a margin, padding, or gap in CSS, the actual visual space between elements often looks larger than what you declared in your code. This discrepancy isn't a bug; it's caused by leading, the typographic whitespace that browsers automatically add above and below each line of text. While this leading improves readability *between* lines, it creates unwanted distortions when it bumps against the outer edges of your text boxes.

For example, a declared 50px margin might visually render as 87px if the text's leading contributes an additional 37px. To hit a target of 50px, you'd have to reverse-engineer the math and set the margin to 13px, a brittle workaround that gets worse as fonts and sizes change.

The Solution: Trimming the Over and Under Edges

The CSS properties text-box-trim and text-box-edge are designed to eliminate this manual compensation. By trimming the leading from the top ("over" edge) and bottom ("under" edge) of a text box, you ensure that declared spacing values like 50px translate exactly to 50px of visible space.

Enabling the Trim with text-box-trim

The text-box-trim property acts as the master switch. It defines which edges—if any—you want to trim. The values are trim-start (top edge), trim-end (bottom edge), trim-both, and none (the default).
Note: For older browser implementations, you may need to use the deprecated start, end, and both values, or even the even older top and bottom values.

Choosing the Trim Point with text-box-edge

The text-box-edge property tells the browser *where* to trim in relation to the font's metrics. A typographic character has multiple visual reference points. It's not just about the literal top and bottom of the glyphs; there are heights for ascenders, capitals, and the x-height, as well as baselines for letters and descenders. This property accepts two values: the first is for the over edge, the second (optional) is for the under edge.

Common Trim Points and Syntax

Here are practical ways to use these properties to align text precisely.

  • Trim above the cap height: To align the top of a button box exactly with the tops of capital letters, use text-box-edge: cap alphabetic along with text-box-trim: trim-both.
  • Trim at the ascender and descender: The text value trims up to the font's ascender and descender heights. This is the default if you don't specify a second value.
  • Opting out of one edge: To trim only the top (e.g., to the cap height) but leave default space at the bottom, you can't just omit the second value—it defaults to text. Instead, you must explicitly set text-box-trim: trim-start and declare only the over-edge value in text-box-edge (e.g., text-box-edge: cap).

This combination—pairing a text-box-edge value with the appropriate text-box-trim action—allows for fine control:

  1. Cap height top, default bottom: Use text-box-edge: cap and text-box-trim: trim-start.
  2. Cap height top, baseline bottom: Use text-box-edge: cap alphabetic and text-box-trim: trim-both. This matches the "Cap height to baseline" preset in Figma's Vertical trim settings.
  3. X-height top only: Use text-box-edge: ex and text-box-trim: trim-start.
  4. Baseline bottom only: Because alphabetic is only a valid value for the under edge, to trim the bottom you must still provide a dummy over-edge value, such as text-box-edge: text alphabetic, and pair it with text-box-trim: trim-end.

Current Limitations and The Shorthand Alternative

There are a few caveats. The keyword auto, intended for "no trim", can only be used on its own (e.g., text-box-edge: auto) and cannot be used to set just the over edge to auto while trimming the under edge. Also, font metrics can be inconsistent—the text value relies on data from the font file itself, which has led to discussions about renaming it to from-font.

For a more concise approach, the text-box shorthand property combines both text-box-trim and text-box-edge into a single declaration. All the rules and values outlined above apply in the same way.