Truncated

Usage

• Use Truncated for names, identifiers, and other single-line values whose length cannot be controlled and that must fit a fixed width while still needing the full value accessible: table cells (resource names, IDs, emails, raw attribute values), list/card titles, panel/drawer headers sharing a row with actions, and badges/menu items with narrow triggers.
• Skip Truncated for values that are always short, like statuses, counts, and dates, and for long-form copy that's important for the user to read — let that content wrap instead.
• Drop Truncated entirely if there's no scenario where the text is ever actually clipped.

Appearance

• Truncated is built on the Text component and inherits its typography props (size, weight, color, family, style, and predefined text style props) — set these directly on Truncated.

Behaviors

• Truncated renders a Tooltip by default that shows the full text on hover/focus; the tooltip only opens when the text is actually clipped, not when it fits its container.
• The tooltip's default content mirrors the visible children.
• Set tooltip to override the tooltip with plain text — use this when the children include a Link or other markup, so the overlay repeats the value as plain text instead of a duplicate interactive element.
• Never write custom tooltip content that explains the truncated value — write it exactly as the value itself, with no supplementary text or formatting.
• Position the tooltip with tooltipPlacement ('bottom' is the default).
  • Use 'bottom' for values in a table row or list.
  • Use 'top' to keep the overlay clear of content below, like a subtitle or row of actions.
  • Use 'left' to keep the overlay clear of content to the right, like a trailing action or badge.
  • Use 'right' to keep the overlay clear of content to the left, like a leading icon or avatar.
• Treat placement as a preference, not a guarantee — the Tooltip repositions itself on small viewports to stay visible.

Implementation Notes

• Content pattern: pass the truncated text as children (React) or the default block (Ember, via {{yield}}) — this is both the visible text and the tooltip's default content when tooltip is unset.
• tooltip only accepts a string — it cannot hold a node or markup, matching the plain-text-only rule for custom tooltip content.
• tooltipPlacement accepts any floating-ui Placement value (e.g. 'top-start', 'bottom-end'), not just the four cardinal directions shown in the design doc.
• Truncated is polymorphic via as (default 'span') since it wraps Text — pass a different element when the surrounding markup requires it.
• Truncation is detected by comparing the rendered element's offsetWidth to its scrollWidth in both frameworks — this is the mechanism behind the tooltip only opening on actual overflow.