Truncated Text

Install

pnpm exec vegastack-design verify truncated-text

pnpm dlx shadcn@4.21.0 add @vegastack/truncated-text

Usage

import { TruncatedText } from "@/components/ui/truncated-text";

<div className="max-w-48">
  <TruncatedText>{longTitle}</TruncatedText>
</div>;

TruncatedText is purely presentational: it applies the truncation utility and, when the text is actually clipped, wraps it in a Tooltip that surfaces the full text on hover or keyboard focus. Width is owned by the parent — constrain the surrounding box (a table cell, a max-w-* wrapper) and the text truncates to fit.

On devices that can't hover (phones, tablets — (hover: none)), Base UI's Tooltip has no touch trigger, so clipped text would otherwise be permanently unreadable. TruncatedText detects this and swaps in a tap-to-toggle disclosure instead: a tap expands the text in place (it wraps instead of clamping), and a second tap, Esc, or blur re-clamps it. Hover-capable devices are unaffected, and keyboard focus keeps opening the Tooltip exactly as before on every device.

Anatomy

Truncated Text is a compound component. Every exported part, with the data-slot it renders (generated from the canonical source):

Examples

Single-line

The default — clamp to one line with a trailing ellipsis. Hover the clipped text to read it in full.

Multi-line

Set lines greater than 1 to clamp to that many lines with CSS line-clamp (supported up to 6). Use as="p" or as="div" for block-level copy.

Line scale

lines={1} truncates to a single line (truncate); 2–6 clamp to that many lines (line-clamp-N). Values above 6 fall back to line-clamp-6. The same overflowing copy is clamped at three line budgets below.

IconText

IconText lays out a fixed leading icon, a truncating label, and an optional trailing slot (a badge, count, or kbd) on a single line. Only the label truncates — the icon and trailing slot stay pinned — and the full label is revealed in a Tooltip when it overflows. The common shape for sidebar items, file rows, and nav labels.

import { IconText } from "@/components/ui/truncated-text";
import { Badge } from "@/components/ui/badge";
import { Icon } from "@vegastack/design/icons";
import { FileText } from "lucide-react";

<div className="max-w-48">
  <IconText
    icon={<Icon as={FileText} />}
    text={fileName}
    trailing={<Badge>New</Badge>}
    tooltipSide="right"
  />
</div>;

The icon is rendered decoratively (aria-hidden), so the label carries the accessible name.

tooltipSide places the overflow tooltip on any edge of the row — top (default), right, bottom, or left.

TableCellText

TableCellText is TruncatedText tuned for table cells: a width that matches the column header so truncation engages predictably, plus an optional mono mode for IDs and paths. It reuses the same overflow measurement and tooltip.

import { TableCellText } from '@/components/ui/truncated-text';

<TableCell>
  <TableCellText text={space.name} width="200px" />
</TableCell>
<TableCell>
  <TableCellText text={space.id} width="160px" mono />
</TableCell>;

mono renders the value in the monospace family at the cell size (text-sm) — for IDs, paths, and other fixed-width values. Set width to match the column header so truncation engages within the column.

Inside tables and link rows

When text is clipped it becomes a Tooltip trigger and takes a tab stop, so keyboard users can read it. In a 50-row table that is 50 extra tab stops on top of DataGrid's own roving cell focus — which is why focusable exists.

It defaults to true standalone. A host that owns its own keyboard model flips the ambient default to false by wrapping its content in TruncationFocusProvider. DataList and DataGrid do exactly that around their tables, so a clipped value or a RelativeTime in a cell is not a tab stop — Tab goes from one row's link straight to the next. Any single cell can opt back in with focusable.

Under such a host, on a device that can hover, a value is measured only when the pointer reaches it: nothing at rest depends on whether it is clipped, so a grid that mounts hundreds of cells per scroll tick pays no layout read and no Tooltip per cell. The full text still opens on hover.

Nothing is hidden either way — CSS truncation is invisible to a screen reader, which reads the full string regardless; the tooltip only ever served sighted keyboard users. Geist and Linear do not make truncated cells focusable either. On a device that cannot hover the element stays focusable no matter what, because the tap-to-toggle disclosure is then the only way to read the text at all.

// A region that owns its own keyboard model turns the tab stops off
<TruncationFocusProvider focusable={false}>{rows}</TruncationFocusProvider>

// …and one cell can still opt back in
<TableCellText text={longNote} focusable />

Playground

Change the line budget, tooltip side, and rendered element on an overflowing string, then copy the generated JSX.

<div className="max-w-48">
  <TruncatedText>{longText}</TruncatedText>
</div>

API Reference

TruncationFocusProvider

TruncatedText

IconText

TableCellText

Accessibility

• Overflow is measured, not assumed — the disclosure (Tooltip or tap-toggle) only engages when the text is genuinely clipped, so screen-reader and keyboard users aren't offered an empty hint when the full text is already visible.
• When clipped, the text becomes a Tooltip trigger and opens on hover and keyboard focus (never hover-only), so the full text is reachable without a pointer. The popup carries role="tooltip".
• focusable controls that tab stop; a TruncationFocusProvider turns it off for a whole region (the grid/list contract). This removes no information: the full string is always in the DOM and always read by assistive tech — the tooltip is a convenience for sighted keyboard users, and inside a grid the roving cell focus is the reachability model.
• Touch fallback: Base UI's Tooltip is hover/focus-only — it has no touch trigger — so on a (hover: none) device the clipped element additionally becomes a tap-to-toggle disclosure: role="button" + aria-expanded track the expand/collapse state, a tap toggles it, and Enter/Space do the same for keyboard activation on hybrid devices. This never replaces the Tooltip — hover-capable devices and keyboard focus behave exactly as before.
• The on-screen (truncated) text remains the element's text content, so the full string is still exposed to assistive technology through the trigger.
• A tooltip supplements text — it is not interactive. Keep links and controls out of the truncated content.

Do / Don't