Text truncation

Single line

EuiTextTruncate provides customizable and size-aware single line text truncation.

The four truncation styles supported are

start, end, startEnd, and middle. Resize the below demo to see how different truncation styles respond to dynamic width changes.

Accessibility and comparison to text-overflow

EuiTextTruncate attempts to mimic the behavior of text-overflow: ellipsis as closely as possible, although there may be edge cases and cross-browser issues, as this is essentially a browser implementation we are trying to polyfill.

Screen readers should ignore the truncated text and only read out the full text.
Sighted mouse users will be able to briefly hover over the truncated text and read the full text in a native browser title tooltip.
For mouse users, double clicking to select the truncated line should allow copying the full untruncated text.

Custom ellipsis

By default, EuiTextTruncate uses the unicode character for horizontal ellipsis. It can be customized via the ellipsis prop as necessary (e.g. for specific languages, extra punctuation, etc).

Truncation offset

The start and end truncation types support a truncationOffset property that allows preserving a specified number of characters at either the start or end of the text. Increase or decrease the number control below to see the prop in action.

Truncation position

The startEnd truncation type supports a truncationPosition property. By default, startEnd anchors the displayed text to the middle of the string. However, you may prefer to display a specific subsection of the full text closer to the start or end, which this prop allows.

This behavior will intelligently detect when positions are near enough to the start or end of the text to omit leading or trailing ellipses when necessary.

Increase or decrease the number control below to see the prop in action.

Render prop

By default, EuiTextTruncate will automatically output the calculated truncated string. You can optionally override this by passing a render prop function to children, which allows for more flexible text rendering.

The below example demonstrates a primary use case for the render prop and the truncationPosition prop. If a user is searching for a specific word in truncated text, you can use

EuiHighlight or EuiMark to highlight the search term, and passing the index of the found word to truncationPosition ensures the search term is always visible to the user.

warning

Do not render excessive extra content alongside the text. The sizing logic will not account for it, and the truncation calculations will be off.

Performance

EuiTextTruncate uses a canvas element under the hood to manipulate text and calculate whether the text width fits within the available width. Additionally, by default, the component will include its own resize observer in order to react to width changes.

These functionalities can cause performance issues if the component is rendered over hundreds of times per page, and we would strongly recommend using caution when doing so. Several escape hatches are available for performance improvements:

Pass a width prop to skip initializing a resize observer for each component instance. For text within a container of the same width, we would strongly recommend applying a single resize observer to the parent container and passing that width to all child EuiTextTruncates. Additionally, you may want to consider throttling any resize observers or width-based logic.
Use virtualization to reduce the number of rendered elements visible at any given time. For over hundreds of instances, this will generally be the most effective solution for performance or rerender issues.
If necessary, consider pulling out the underlying TruncationUtils and re-using the same canvas context, as opposed to repeatedly creating new ones.

Multi line

EuiTextBlockTruncate allows truncating text after a set number of wrapping lines.

Please note: This component is currently a quick shortcut for the CSS line-clamp property. This means that truncating at the end of the text is the default, and there are currently no plans to add JavaScript customization for this behavior.

Props

EuiTextTruncate

Extends HTMLAttributes


Prop	Description and type	Default value
Prop text#	Description and type The full text string to truncate Type: `string`	Default value Required
Prop className#	Description and type Type: `string`	Default value
Prop aria-label#	Description and type Defines a string value that labels the current element. @see aria-labelledby. Type: `string`	Default value
Prop data-test-subj#	Description and type Type: `string`	Default value
Prop css#	Description and type Type: `Interpolation<Theme>`	Default value
Prop truncation#	Description and type The truncation type desired. Determines where the ellipses are placed. Type: `"end" \| "start" \| "middle" \| "startEnd"`	Default value
Prop truncationOffset#	Description and type This prop only applies to the `start` and `end` truncation types. It allows preserving a certain number of characters of either the starting or ending text. If the passed offset is greater than the total text length, the offset will be ignored. Type: `number`	Default value
Prop truncationPosition#	Description and type This prop only applies to the `startEnd` truncation type. It allows customizing the anchor position of the displayed text, which otherwise defaults to the middle of the text string. The primary use case for this prop for is search highlighting - e.g., if a user searches for a specific word in the text, pass the index of that found word to ensure it is always visible. This behavior will intelligently detect when positions are close to the start or end of the text, and omit leading or trailing ellipses when necessary. If the passed position is greater than the total text length, the truncation will simply default to `start` instead. Type: `number`	Default value
Prop ellipsis#	Description and type Defaults to the horizontal ellipsis character. Can be optionally configured to use other punctuation, e.g. spaces, brackets, hyphens, asterisks, etc. Type: `string`	Default value `…`
Prop width#	Description and type By default, EuiTextTruncate will render a resize observer to detect the available width it has. For performance reasons (e.g. multiple truncated text items within the same container), you may opt to pass in your own container width, which will skip initializing a resize observer. Type: `number`	Default value
Prop onResize#	Description and type Optional callback that fires when the default resizer observer both mounts and registers a size change. This callback will not fire if `width` is passed. Type: `(width: number) => void`	Default value
Prop children#	Description and type By default, EuiTextTruncate will render the truncated string directly. You can optionally pass a render prop function to the component, which allows for more flexible text rendering, e.g. adding custom markup or highlighting Type: `(truncatedString: string) => ReactNode`	Default value
Prop calculationDelayMs#	Description and type For some edge case scenarios, EuiTextTruncate's calculations may be off until fonts are done loading or layout is done shifting or settling. Adding a delay may help resolve any rendering issues. Type: `number`	Default value

EuiTextBlockTruncate