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
CodeBlockfor a value that may wrap over several lines, or let it wrap. - Prefer
Codefor a short fragment of inline code that never overflows.
When not to use
- For prose that may lose its end. Use the
truncateutility.
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.Valuealready sizes its column that way. - An auto-layout table grows its column to the full value, even with a column width. Set
table-layout: fixedon 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
ResizeObserverserves 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: