Stirling-PDF/frontend/src/components/shared/fitText/FitText.README.md

FitText Component

Adaptive text component that automatically scales font size down so the content fits within its container, with optional multi-line clamping. Built with a small hook wrapper around ResizeObserver and MutationObserver for reliable, responsive fitting.

Features

• 📏 Auto-fit text to available width (and optional line count)
• 🧵 Single-line and multi-line support with clamping and ellipsis
• 🔁 React hook + component interface
• ⚡ Efficient: observers and rAF, minimal layout thrash
• 🎛️ Configurable min scale, max font size, and step size

Behavior

• On mount and whenever size/text changes, the font is reduced (never increased) until the text fits the given constraints.
• If lines is provided, height is constrained to an estimated maximum based on computed line-height.

Basic Usage

import FitText from '@/components/shared/FitText';

export function CardTitle({ title }: { title: string }) {
  return (
    <FitText text={title} />
  );
}

API Reference

Props

Prop	Type	Default	Description
text	string	—	The string to render and fit
fontSize	number	computed	Maximum starting font size in rem (e.g., 1.2, 0.9)
minimumFontScale	number	0.8	Smallest scale relative to the max (0..1)
lines	number	1	Maximum number of lines to display and fit
className	string	—	Optional class on the rendered element
style	CSSProperties	—	Inline styles (merged with internal clamp styles)
as	`'span'	'div'`	'span'

Notes:

• For multi-line, the component applies WebKit line clamping (with reasonable fallbacks) and fits within that height.
• The component only scales down; if the content already fits, it keeps the starting size.

Examples

Single-line title (default)

<FitText text="Very long single-line title that should shrink" />

Multi-line label (up to 3 lines)

<FitText
  text="This label can wrap up to three lines and will shrink so it fits nicely"
  lines={3}
  minimumFontScale={0.6}
  className="my-multiline-label"
/>

Explicit starting size

<FitText text="Starts at 1.2rem, scales down if needed" fontSize={1.2} />

Render as a div

<FitText as="div" text="Block-level content" lines={2} />

Hook Usage (Advanced)

If you need to control your own element, you can use the underlying hook directly.

import React, { useRef } from 'react';
import { useAdjustFontSizeToFit } from '@/components/shared/fitText/textFit';

export function CustomFit() {
  const ref = useRef<HTMLSpanElement | null>(null);

  useAdjustFontSizeToFit(ref as any, {
    maxFontSizePx: 20,
    minFontScale: 0.6,
    maxLines: 2,
    singleLine: false,
  });

  return (
    <span ref={ref} style={{ display: 'inline-block', maxWidth: 240 }}>
      Arbitrary text that will scale to fit two lines.
    </span>
  );
}

Tips

• For predictable measurements, ensure the container has a fixed width (or stable layout) when fitting occurs.
• Avoid animating width while fitting; update after animation completes for best results.
• When you need more control of typography, pass fontSize to define the starting ceiling.
• Important: The fontSize prop expects rem values (e.g., 1.2, 0.9) to ensure text scales with global font size changes.