react-truncate-markup-eden
v2.0.5
Published
React component for truncating JSX markup
Downloads
3
Maintainers
Readme
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 settingdisplay: 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
andprop-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.
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.
onAfterTruncate
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.
Contributing
Read more about project setup and contributing in CONTRIBUTING.md
License
Released under Apache-2.0 license.
Copyright © 2017-present Parsable Inc.