React-truncate-markup NPM

React Truncate Markup

React component for truncating JSX markup.

Examples with code snippets
CodeSandbox demo

Why?

Few use cases for using JS truncating instead of the CSS one:

you need to support IE, Firefox or Edge (and cannot use webkit-line-clamp) for multi-line truncation
you need a custom ellipsis, potentially with more text (show more link, indicator of how many records were hidden by truncation, etc.)

Most solutions that already exist (like react-truncate or React-Text-Truncate) use HTML5 canvas (and its measureText method) for measuring text width to determine whether (and where) the provided text should be truncated.

While this approach is valid, it has its limitations - it works only for plain text, and not for JSX markup. You might want to use JSX when parts of the text have different style (like color or font-weight).

How?

Because we need to determine how to truncate provided content after all the layout and styles were applied, we need to actually render it in browser (instead of rendering it off-screen in canvas).

By using a binary search approach (splitting JSX in half and checking if the text + ellipsis fit the container, and if not, splitting it in half again, and so on), depending on the size (and depth) of the markup, it usually takes only a few rerenders to get the final, truncated markup.

Performance was not an issue for our use cases (e.g. using TruncateMarkup twice per list item in a dropdown list containing dozens of items), there is no text movement visible on the screen (but YMMV).

Note: Because this package depends on browser rendering, all elements inside <TruncateMarkup /> need to be visible. If you need to hide or show some parts of your UI, consider conditionally rendering them instead of setting display: none/display: block style on the elements.

Installation

npm install --save react-truncate-markup
# or
yarn add react-truncate-markup

This package also depends on react and prop-types. Please make sure you have those installed as well.

Importing:

// using ES6 modules
import TruncateMarkup from 'react-truncate-markup';

// using CommonJS modules
const TruncateMarkup = require('react-truncate-markup').default;

Or using script tags and globals:

<script src="https://unpkg.com/react-truncate-markup/umd/react-truncate-markup.min.js"></script>

And accessing the global variable:

const TruncateMarkup = ReactTruncateMarkup.default;

Usage

<div style={{ width: '200px' }}> /* or any wrapper */
  <TruncateMarkup lines={2}>
    <div>
      /* ... any markup ... */
      <span style={{ color: 'red' }}>
        <strong>{this.props.subject}:</strong>
      </span>
      {` `}
      {this.props.message}
    </div>
  </TruncateMarkup>
</div>

:warning: Warning
Only inlined DOM elements are supported when using this library. When trying to truncate React components (class or function), <TruncateMarkup /> will warn about it, skip truncation and display the whole content instead. For more details, please read this comment.
Or, since version 5, you can take advantage of the <TruncateMarkup.Atom /> component.

Props

`children`

It's required that only 1 element is passed as children.

Correct:

<TruncateMarkup>
  <div>
    /* ... markup ... */
  </div>
</TruncateMarkup>

Incorrect:

<TruncateMarkup>
  /* ... markup ... */
  <div>/* ... */</div>
  <div>/* ... */</div>
</TruncateMarkup>

`lines`

default value: 1

Maximum number of displayed lines of text.

`ellipsis`

default value: ...

Appended to the truncated text.

One of type: [string, JSX Element, function]

string: ...
JSX Element: <span>... <button>read more</button></span>
function: function(jsxElement) { /* ... */ }

Ellipsis callback function receives new (truncated) <TruncateMarkup /> children as an argument so it can be used for determining what the final ellipsis should look like.

const originalText = '/* ... */';

const wordsLeftEllipsis = (rootEl) => {
  const originalWordCount = originalText.match(/\S+/g).length;
  const newTruncatedText = rootEl.props.children;
  const currentWordCount = newTruncatedText.match(/\S+/g).length;

  return `... (+${originalWordCount - currentWordCount} words)`;
}

<TruncateMarkup ellipsis={wordsLeftEllipsis}>
  <div>
    {originalText}
  </div>
</TruncateMarkup>

`lineHeight`

default value: auto-detected

Numeric value for desired line height in pixels. Generally it will be auto-detected but it can be useful in some cases when the auto-detected value needs to be overridden.

`onTruncate`

function(wasTruncated: bool) | optional

A callback that gets called after truncation. It receives a bool value - true if the input markup was truncated, false when no truncation was needed.

Note: To prevent infinite loops, onTruncate callback gets called only after the initial run (on mount), any subsequent props/children updates will trigger a recomputation, but onTruncate won't get called for these updates.
If you, however, wish to have onTruncate called after some update, change the key prop on the <TruncateMarkup /> component - it will make React to remount the component, instead of updating it.

`tokenize`

default value: characters

By default, any single character is considered the smallest, undividable entity, so the input markup can be truncated at any point (even midword). To override this behaviour, you can set the tokenize prop to following values:

characters - default the input text can be truncated at any point
words - each word, separated by a whitespace character, is undividable entity. The only exception to this are words separated by the &nbsp character, which are still honored and can be used in case you want to keep the words together

`<TruncateMarkup.Atom />`

Atoms serve as a way to let <TruncateMarkup /> know that the content they contain is not splittable - it either renders in full or does not render at all.

There are two main applications of Atoms: 1. you want to control at what level the truncation happens (and splitting on the word level using tokenize="word" is not enough), e.g. split text by paragraphs 2. you want/need to use other components inside <TruncateMarkup />

On itself, <TruncateMarkup /> will not truncate any content that contains other components (see the warning box above). But it's still a useful feature.

Consider this case: We want to render a list of avatars and if we run out of space, we want to render however many avatars fit, plus a custom message "+X more users", with X being the number of users that are not rendered.

<TruncateMarkup ellipsis={() => {/* renders "+X more users" */}}>
  <div>
    {props.users.map((user) => (
      <Avatar key={user.id} user={user} />
    ))}
  </div>
</TruncateMarkup>

This would not work because <TruncateMarkup /> cannot split anything inside other components (in this case, <Avatar />), so it bails out and doesn't even attempt to truncate. But by explicitely wrapping these components in <TruncateMarkup.Atom /> we say we are ok with it being treated as a single piece (rendered either in full or not rendered at all), whether they contain other components or not.

<TruncateMarkup ellipsis={() => {/* renders "+X more users" */}}>
  <div>
    {props.users.map((user) => (
      <TruncateMarkup.Atom key={user.id}>
        <Avatar user={user} />
      </TruncateMarkup.Atom>
    ))}
  </div>
</TruncateMarkup>

You can see this example in action in the examples/demo app.