Skip to main content
Elastic UI
Elastic UI
Getting startedComponentsPatternsContentData visualization
EUI ChangelogGitHubFigma
  • Setup
  • Theming
  • Accessibility
  • Testing
  • Utilities
    • Accessibility
    • Auto sizer
    • Color palettes
    • Copy
    • CSS utility classes
    • Delay
    • Error boundary
    • Focus trap
    • Highlight and mark
    • HTML ID generator
    • I18n
    • Inner text
    • Mutation observer
    • Outside click detector
    • Overlay mask
    • Portal
    • Pretty duration
    • Provider
    • Resize observer
    • Scroll
    • Text diff
    • Text truncation
    • Window events
  • EUI
  • Utilities
  • Text truncation

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.

Loading...

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).

Loading...

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.

Loading...

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.

Loading...

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.

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

Loading...

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:

  1. 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.

  2. 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.

  3. If necessary, consider pulling out the underlying TruncationUtils and re-using the same canvas context, as opposed to repeatedly creating new ones.

Loading...

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.

Loading...

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

Extends HTMLAttributes
𐘂𐘂
✄𐘗✄𐘗
Prop
↦
Description and type
↦
Default value
↵
Prop
lines#
↦
Description and type

Number of lines of text to truncate to

Type: number
↦
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
cloneElement#
↦
Description and type

Applies styling to the child element instead of rendering a parent wrapper div.
Can only be used when wrapping a single child element/tag, and not raw text.

Type: boolean
↦
Default value
↵
𐘂𐘂
Edit this page

Previous
Text diff
Next
Window events
  • Single line
    • Custom ellipsis
    • Truncation offset
    • Truncation position
    • Render prop
    • Performance
  • Multi line
  • Props
EUI is dual-licensed under Elastic License 2.0 and Server Side Public License, v 1 | Crafted with ❤ by Elastic