Fit And Rebuild

fit scales text so it fills the available container width. It produces CSS variables you apply to control the font size.

Basic Usage

<h1 string="split" string-split="line[start]|fit">Big Headline Text</h1>

h1 .-s-line {
  font-size: calc(var(--fit-font-size) * 1px);
}

The module computes a font size that makes the text fill the container content width and writes it as a CSS variable. You decide how to apply it.

Behavior With Line Split

When the config includes a line-level token (line, word-line, or char-line), fit computes a separate value per line:

• --fit-font-size is set on each .-s-line span
• Each line can fill the width independently
• Shorter lines get a larger font size, longer lines get a smaller one

<h1 class="fit-demo" string="split" string-split="word-line[start]|fit">Short<br />Medium length<br />The full wide headline</h1>

/* .-s-line clips its children and holds the per-line font size */
.fit-demo .-s-line {
  display: block;
  overflow: hidden;
  font-size: calc(var(--fit-font-size, 10) * 1px);
}

/* .-s-word inherits --line-index from its parent .-s-line */
.fit-demo .-s-word {
  display: inline-block;
  transform: translateY(110%);
  animation: lineReveal 0.75s cubic-bezier(0.2, 0, 0, 1) forwards;
  animation-delay: calc(var(--line-index, 0) * 0.14s + 0.15s);
}

@keyframes lineReveal {
  to {
    transform: translateY(0);
  }
}

word-line creates both .-s-line and .-s-word wrappers. The .-s-line acts as a clip mask while .-s-word slides up through it. Because CSS custom properties inherit down the tree, --line-index set on .-s-line is available inside every .-s-word descendant — no JavaScript needed to stagger per line.

Behavior Without Line Split

When there is no line-level token, fit uses the widest line and writes values on the source element:

<h1 string="split" string-split="char[start]|fit">Typography</h1>

h1 {
  font-size: calc(var(--fit-font-size) * 1px);
}

Char Split And Spaces

When char wrappers are active (char, char-line, or char-word), inter-word spaces are not wrapped in .-s-char spans. They stay as regular text nodes and do not scale with font-size.

The fit calculation accounts for this automatically — scalable character width and non-scalable space width are handled separately. This is why fit with char splits produces accurate results even with multi-word lines.

Accuracy

The module performs a two-pass measurement:

1. Compute a provisional font size from the text/container ratio
2. Render at that size and refine based on the actual result

This handles kerning, sub-pixel rendering, and other browser-specific effects. The final result may deviate by up to 1px from mathematically perfect fill due to Math.floor() rounding.

Rebuild Timing

The split DOM is rebuilt:

• on initial connection
• on desktop width resize
• on reconnect

Each rebuild starts from the cached original HTML, so the result is always clean.

Mobile

Mobile rebuilds are disabled by default:

• Width changes on mobile do not trigger a rebuild
• Height changes on mobile do not trigger a rebuild

If you need responsive fit on mobile, the initial render uses the viewport width at load time.

Restore After

<h1 string="split" string-split="line[start]|fit" string-split-restore-after="3000">Intro Text</h1>

After 3000ms, the module restores the original HTML and adds class -restored. The split DOM and fit variables are no longer available.

Use this for one-shot intro effects where the split is temporary.

Caveats

• Fit is measurement-heavy — it requires multiple layout passes. Avoid applying it to large numbers of elements simultaneously.
• The module uses the element's content width (excluding padding) as the target. If the element's width changes after initial render, a width resize triggers a recalculation.
• If your animation depends on split wrappers always being present, do not combine fit with string-split-restore-after unless the one-shot behavior is intentional.

Related

• Base module page: StringSplit
• Grammar: Split Grammar
• DOM output: DOM Output
• Inline HTML: Inline HTML