pretext-ellipsis

React component for multi-line text truncation with an action slot (button, icon, badge, etc.) at the end of the last line.

Built on top of @chenglou/pretext — a fast, canvas-based text measurement library that avoids DOM layout reflows.

The problem

CSS text-overflow: ellipsis only works on a single line. CSS -webkit-line-clamp truncates at N lines but gives you no control over what appears after the ellipsis. You can't reliably place a "Read more" button at the exact end of the last truncated line — especially when the container width changes.

The solution

<PretextEllipsis> uses @chenglou/pretext to measure text layout without triggering DOM reflows, reserves space for your action element on the last line, and renders the truncated text with the action in the right place. The action only appears when the text exceeds maxLines — if it fits naturally, no action is shown.

┌──────────────────────────────────────┐
│ This is a long paragraph of text     │
│ that demonstrates how the comp… More │
└──────────────────────────────────────┘
                                  ^^^^^ visible when truncated

Demo

Live demo

Install

npm install pretext-ellipsis

Peer dependencies: react >= 18, react-dom >= 18.

Usage

import { PretextEllipsis } from "pretext-ellipsis";

function Example() {
  const [expanded, setExpanded] = useState(false);

  return (
    <PretextEllipsis
      maxLines={2}
      expanded={expanded}
      action={
        <button
          onClick={() => setExpanded(!expanded)}
          style={{ marginLeft: 4, color: "#2563eb", fontWeight: 600 }}
        >
          {expanded ? "Less" : "More"}
        </button>
      }
      style={{ fontSize: 16, lineHeight: "24px" }}
    >
      Your long text goes here...
    </PretextEllipsis>
  );
}

The component reads font-size, font-family, font-weight, and line-height directly from CSS (computed styles). No need to pass them as props.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | string | (required) | The text content to display. | | maxLines | number | 2 | Maximum number of visible lines before truncation. | | action | ReactNode | — | Element rendered at the end of the last line when text exceeds maxLines. | | breakMode | "word" \| "char" | "word" | How to break text on the last truncated line. | | ellipsis | string | "…" | Ellipsis string inserted before the action. | | className | string | — | CSS class applied to the container. | | style | CSSProperties | — | Inline styles (font, colors, etc.) applied to the container. | | expanded | boolean | false | When true, shows the full text with an animated height transition. | | expandAnimation | boolean | true | Whether to animate the expand/collapse transition. Set to false for an instant switch. |

Break modes

"word" (default)

Truncates at word boundaries. There may be a small gap between the end of the text and the ellipsis.

demonstrates how the… More

"char"

Truncates at character/grapheme boundaries to fill the available line width. The ellipsis sits flush at the end of the line.

demonstrates how the compon… More

Expand / collapse

Toggle expanded to reveal the full text with a smooth height animation. The action slot stays visible on the last line in both states, so a single button can serve as a "Read more" / "Read less" toggle.

The height transition uses @chenglou/pretext's layoutWithLines() to calculate the expanded height without DOM reflow — the same technique as the accordion demo in the pretext repo. Set expandAnimation={false} to disable the transition and switch instantly.

How it works

1. A ResizeObserver tracks the container width and reads font / line-height from computed styles.
2. @chenglou/pretext prepares and caches text segment widths using canvas measureText() — no DOM reflow.
3. On resize, the component calculates line breaks: full width for lines 1 through N-1, reduced width (minus the action's measured width) for line N.
4. If the text exceeds maxLines, the last line is truncated and the action is rendered inline.
5. If the text fits naturally, it renders as-is with no ellipsis or action.
6. When expanded is toggled, the container height animates between the truncated and full heights via a CSS transition.

Notes

• Browser-only — requires document and canvas. Not compatible with SSR / Node.js rendering.
• Font loading — for accurate measurement, ensure fonts are loaded before the component renders. The component uses getComputedStyle to read the active font, which reflects the fallback font if the primary hasn't loaded yet.
• Action visibility — the action prop only renders when text is truncatable (exceeds maxLines). It stays visible in both collapsed and expanded states. If the text fits within maxLines, no action is shown.

License

MIT