Skip to main content

Truncated Text

Renders one long opaque value, such as a URL, a resource ID, a container image reference, or a token, on a single line and keeps its tail visible when it overflows.

When to use

  • A URL, an ID, an image reference, or a token in a table cell, a description list, or a card, where the end of the value matters.
  • Prefer CodeBlock for a value that may wrap over several lines, or let it wrap.
  • Prefer Code for a short fragment of inline code that never overflows.

When not to use

  • For prose that may lose its end. Use the truncate utility.

Polymorphism

Pass asChild to render the value inside a different element instead of the default <span>. The child must have no children of its own, because value is the content, and it must render children directly, as <code> does: TruncatedText renders the two segments inside the child. The class names, data-* attributes, and the ref land on that child.

How it truncates

When the value overflows its container, the head clips with one ellipsis and the last eight graphemes stay visible. When the value fits, it renders plain. Hover a clipped value to read the whole thing in a tooltip.

The tail is the part that tells values apart. Two URLs share a 60-character prefix and differ in the last path segment. Two IDs share a prefix and differ in the last six characters. A plain truncate hides exactly the part you need, so TruncatedText keeps it.

Drag the corner of the box in the first example on this page to see the head give way while the tail stays put.

Tail length

tail is the number of graphemes that stay visible, 8 by default. Count what tells your values apart: an ngrok resource ID ends in the characters that differ, so tail={6} keeps them. The count is in grapheme clusters, so an emoji or a letter with a combining mark never splits in half.

Head length

head is the most graphemes that show before the ellipsis. Without it, the head fills the container. With it, a value longer than head + tail graphemes always clips to the same shape, and the root shrinks to fit. A narrower container still clips the head further. An ngrok resource ID starts with a type prefix, so head={id.indexOf("_") + 1} keeps the prefix and the ID shows as mem_…A8KImPbQ.

The head rounds up to whole ch cells. In a monospace font the shape is exact. In a proportional font, one more narrow glyph can show before the ellipsis.

Style the head and the tail

The head and the tail are two <span> elements, data-slot="truncated-text-head" and data-slot="truncated-text-tail". Style each one from the root with a *:data-[slot=…]: class. Change a segment's color, not its font: the component measures the whole value in the root's font, so set a font on the root. CSS draws the ellipsis at the end of the head, so the ellipsis takes the head's color. To mute the type prefix of an ID and keep its tail at body color, pass head and color the head:

The two segments render when the value fits too, so these classes also color a value that fits. To color the segments only while the value overflows, add the data-truncated: variant first: data-truncated:*:data-[slot=truncated-text-head]:text-muted. A value no longer than tail has an empty head, so its tail draws the ellipsis in the tail's color.

Selection

The root carries user-select: all, so one click selects the whole value across both segments, and a copy yields the full string. CSS draws the ellipsis, so a selection never contains it. The two segments copy as one line. Click the value below, then copy it. Pass className="select-text" to get normal text selection instead.

Layout

The container decides the width. TruncatedText is an inline-block that grows to its container's width and no further, so the container has to stop growing first:

  • A flex item needs min-w-0, or it refuses to shrink below the full value.
  • A grid track needs minmax(0, 1fr). DescriptionList.Value already sizes its column that way.
  • An auto-layout table grows its column to the full value, even with a column width. Set table-layout: fixed on the table and give the table a width.

When the container holds less than the tail and one cell, the ellipsis is all that remains of the head. The tail then clips at its start, so the end of the value is the last thing to go. A value no longer than tail has no head, so its tail draws the ellipsis itself. Give the value a line of its own: beside other inline text, an overflowing value wraps to the next line at the container's full width. The root sets dir="ltr", because a URL, an ID, or a token reads left to right on an RTL page too. A dir prop wins.

The component sets no font, but it turns ligatures off, so a // or => clips between its two characters. The ellipsis sits flush against the tail in any font, and it stays flush while the container resizes.

The server render reserves one ch per grapheme for the tail, which is exact in a monospace font. In another font the server paint of an overflowing value can be off by the difference: a tail of wide glyphs (CJK, emoji) can poke past the container, and a value that fits by less than the over-reserve of narrow glyphs can clip. On the client, the measurement runs after the commit and before the browser paints.

Performance

TruncatedText is built for tables with many rows:

  • Each instance renders once on mount. One batch measures every instance that mounted in the commit: it reads all of them first, then writes all of them, so the page lays out once for the batch and not once for each row.
  • The tooltip mounts on the first hover or keyboard focus while the value overflows. A table of values mounts no tooltip until a reader asks for one.
  • One ResizeObserver serves every instance, and a resize writes the DOM in the same frame. A resize renders no React component.

A table still lays out each cell that it renders. Paginate a long table: see Table.

Tooltip

The tooltip shows the whole value. It is up to 24rem wide, so a resource ID fits on one line. A longer value breaks into lines of near-equal length, so the last line never holds only one or two characters, and the tooltip narrows to the longest line. Hover each value below.

Accessibility

A screen reader reads the whole value as one string. The two visible segments are aria-hidden, because Chromium puts a space between two inline-block boxes in an accessible name, and a visually hidden <span> holds the whole value instead. That copy carries user-select: none, so one click still copies the value once. A page-wide select-all copies it twice, like any visually hidden label. The ellipsis is a CSS effect, so nothing announces it.

The tooltip opens on hover only while the value overflows. It needs a TooltipProvider ancestor, like every mantle tooltip. Without one, it throws when the tooltip first mounts. While the value overflows, the root is focusable, so Tab reaches it, a screen reader announces the whole value, and the tooltip opens. A value that fits isn't a tab stop. A tabIndex prop wins in both states.

Inside a control (a <button>, an <a href>, a radio, a menu item, a tab) the root takes no tab stop and opens no tooltip, because a control cannot hold a second one. The segments still clip, data-truncated still lands, and the hidden copy gives the control's accessible name the whole value. Wrap the control in Tooltip when a sighted reader needs the full value. The server render and the first client render assume no control, like they assume no overflow; each commit after that reads the DOM again.

Translation

The root and the tooltip carry translate="no" by default, so a browser translation engine skips the value. A translated URL or ID is wrong, and the reader copies it anyway. When the value is prose, pass translate="yes". Browser translation covers what an engine does to a React DOM.

API Reference

TruncatedText

All props from span, plus:

PropTypeDefaultDescription
asChild?booleanfalseRender the value inside the single child element instead of a <span>. The child must have no children of its own.
className?stringAdditional CSS classes to apply to the root. select-text turns off the one-click selection.
dir?"ltr" | "rtl" | "auto""ltr"The text direction. The default keeps the tail on the right on an RTL page.
head?numberThe most graphemes that show before the ellipsis. A longer value always clips to head and tail, and the root shrinks to fit. A non-negative integer.
tail?number8How many graphemes stay visible at the end of the value. Counts grapheme clusters, so an emoji or a letter with a combining mark counts once. A non-negative integer.
translate?"yes" | "no""no"Whether a browser translation engine may translate the value and its tooltip. When the value is prose, pass "yes".
valuestringThe full value. Required.

Data attributes

Data AttributeValueDescription
data-slot"truncated-text"On the root, and joined onto the child via asChild.
data-slot"truncated-text-head"On the <span> that clips. Holds everything before the tail.
data-slot"truncated-text-tail"On the <span> that stays visible. Holds the last tail graphemes.
data-slot"truncated-text-value"On the visually hidden <span> that holds the whole value for assistive technology.
data-truncatedpresent while the value overflowsPresence-only. Style with data-truncated:. Absent on the server render.
data-state"closed" | "delayed-open" | "instant-open"The tooltip state on the root. "closed" until the tooltip mounts. Absent inside a control.