{
"name": "TruncatedText",
"source": "src/components/TruncatedText.tsx",
"propsType": "TruncatedTextProps",
"description": "TruncatedText — long text cut to its space, with the whole of it still\nreachable.\n\nNOT HOVER ONLY. A `title` attribute, or a tooltip on hover, leaves the rest\nof the text to mouse users. Here a cut line is also a tab stop that opens\nthe same tooltip on focus, and a cut paragraph has a real Show more button.\n\nONLY WHEN IT IS CUT. It measures itself, and while the text fits it is\nplain text: no tab stop, no tooltip, no button. A narrower window can cut\nit later; it measures again when its size changes.\n\nTHE WHOLE TEXT IS ALWAYS THERE. It is cut by CSS, not by dropping\ncharacters, so a screen reader reads all of it, find-in-page finds it, and\na copy copies it. The tooltip repeats text already read, so it is kept out\nof the accessible description rather than read twice.\n\nIT INHERITS THE FONT. It sits inside whatever sets the type — a caption, a\ntable cell — and takes its size, weight and colour.",
"import": "import { TruncatedText } from 'ionbase-ui';",
"status": "stable",
"summary": "Long text cut to its space — a line in a table cell, a paragraph under a heading — with the whole of it still reachable: a cut line is a tab stop with a tooltip on hover and focus, a cut paragraph has a Show more button. While the text fits it is plain text. The whole text is always in the DOM, so a screen reader reads all of it.",
"useWhen": [
"text of any length lands in a space of fixed size — a description in a table row, a name in a card, a summary in a list",
"the text is written by users or agents, so no one can promise it is short"
],
"useInstead": [
{
"when": "the text is short by construction — a status, a label you wrote",
"use": "plain text",
"why": "a label that is cut was written for a space it does not fit; shorten it instead"
},
{
"when": "an ID or key the user needs whole",
"use": "CopyButton",
"why": "an ID is copied, not read; cutting it hides the part that tells two apart"
},
{
"when": "a long block of code or output",
"use": "CodeSnippet",
"why": "it cuts by lines with Show more too, and keeps the code's spacing and a copy button"
}
],
"composition": {
"order": [
"TruncatedText"
],
"note": "`children` is the text, as a string. It takes the font of whatever it is in — put a caption class on it or on its parent. It never widens what it sits in: in a table cell, a grid or a flex row it shrinks to the space it is given and is cut there. `lines` above 1 clamps by line count; `overflow=\"expand\"` swaps the tooltip for Show more, which a paragraph needs.",
"example": "{agent.purpose}"
},
"variants": {
"overflow": {
"tooltip": {
"use": "the default — a short line in a narrow place: the cut line is a tab stop, and the tooltip shows the whole text on hover and focus"
},
"expand": {
"use": "a paragraph, with `lines` above 1 — Show more opens it in place, since a tooltip is too small to hold it"
}
}
},
"a11y": {
"requires": [
"plain text as `children` — nothing interactive inside a line that may be cut"
],
"guarantees": [
"the whole text is in the DOM, cut by CSS: a screen reader reads all of it, find-in-page finds it, a copy copies it",
"a cut line is a tab stop, and focus opens the same tooltip as hover; Escape closes it",
"the tooltip is not the text's description — it repeats what is already read, so a screen reader does not hear it twice",
"Show more is a real button, with aria-expanded and aria-controls pointing at the text",
"text that fits is plain text: no tab stop, no tooltip, no button; it measures again when its size changes"
],
"notes": [
"a `title` attribute is hover-only and never reaches a keyboard — this replaces it",
"the focus ring is drawn inside the text's box, so a table's scroll container cannot clip it",
"it never widens its container: a table column, a grid track or a flex item shrinks to its share and cuts it"
]
},
"antiPatterns": [
{
"dont": "{purpose}",
"do": "{purpose}",
"why": "a title appears on hover only, after a delay; a keyboard or touch user never gets the rest of the text"
},
{
"dont": "{purpose.slice(0, 40) + '…'}",
"do": "{purpose}",
"why": "the rest is gone from the page: a screen reader, find-in-page and a copy all get the stub"
},
{
"dont": "{longDescription}",
"do": "{longDescription}",
"why": "a tooltip holds a sentence; a paragraph in one is unreadable and closes when the pointer leaves"
}
],
"stylesheet": "src/styles/truncated-text.css",
"tokens": [
"--border-focus",
"--border-width-thick",
"--ion-truncated-lines",
"--radius-xs",
"--spacing-4"
],
"props": {
"children": {
"type": "string",
"required": true,
"origin": "own",
"description": "The whole text. Plain text only: it is what the tooltip shows, and a\nlink or a button inside a cut line would be cut with it."
},
"lines": {
"type": "number | undefined",
"required": false,
"origin": "own",
"description": "Lines shown before the text is cut. Default 1."
},
"overflow": {
"type": "TruncatedTextOverflow | undefined",
"required": false,
"origin": "own",
"description": "How the rest is reached once the text is cut.\n\n`tooltip` — the cut text becomes a tab stop and shows the whole text on\nhover and on focus. For short text in a narrow place: a table cell, a\ncard's subtitle.\n\n`expand` — a Show more button below it opens the text in place. For a\nparagraph, which a tooltip is too small to hold.",
"values": [
"tooltip",
"expand"
]
},
"showMoreLabel": {
"type": "string | undefined",
"required": false,
"origin": "own",
"description": "`expand` only. Default \"Show more\"."
},
"showLessLabel": {
"type": "string | undefined",
"required": false,
"origin": "own",
"description": "`expand` only. Default \"Show less\"."
},
"placement": {
"type": "TooltipPlacement | undefined",
"required": false,
"origin": "own",
"description": "`tooltip` only: where the tooltip sits. Default `top`.",
"values": [
"top",
"bottom",
"left",
"right"
]
},
"className": {
"type": "string | undefined",
"required": false,
"origin": "own"
}
},
"propCounts": {
"own": 7,
"aria": 0,
"dom": 0,
"other": 0
}
}