Truncate html string(even contains emoji chars) and keep tags in safe. You can custom ellipsis sign, ignore unwanted elements and truncate html by words.

consttruncate=require('truncate-html')truncate('<p><img src="xxx.jpg">Hello from earth!</p>',2,{byWords:true})// => <p><img src="xxx.jpg">Hello from ...</p>

Installation

Try it online

API

/** * custom node strategy, default to Cheerio<AnyNode> * * 'remove' to remove the node * * 'keep' to keep the node(and anything inside it) anyway, and won't be counted as there is no text content in it * * Cheerio<AnyNode> truncate the returned node * * undefined or any falsy value to truncate original node */typeICustomNodeStrategy=(node:Cheerio<AnyNode>)=>'remove'|'keep'|Cheerio<AnyNode>|undefined/** * truncate-html full options object */interfaceIFullOptions{/**   * remove all tags, default false   */stripTags:boolean/**   * ellipsis sign, default '...'   */ellipsis:string/**   * decode html entities(e.g. convert `&amp;` to `&`) before counting length, default false   */decodeEntities:boolean/**   * elements' selector you want ignore   */excludes:string|string[]/**   * custom node strategy, default to Cheerio<AnyNode>   * * 'remove' to remove the node   * * 'keep' to keep the node(and anything inside it) anyway, and won't be counted as there is no text content in it   * * Cheerio<AnyNode> truncate the returned node   * * undefined or any falsy value to truncate original node   */customNodeStrategy:ICustomNodeStrategy/**   * how many letters(words if `byWords` is true) you want reserve   */length:number/**   * if true, length means how many words to reserve   */byWords:boolean/**   * how to deal with when truncate in the middle of a word   *  1. by default, just cut at that position.   *  2. set it to true, with max exceed 10 letters can exceed to reserver the last word   *  3. set it to a positive number decide how many letters can exceed to reserve the last word   *  4. set it to negative number to remove the last word if cut in the middle.   */reserveLastWord:boolean|number/**   * if reserveLastWord set to negative number, and there is only one word in the html string,  when trimTheOnlyWord set to true, the extra letters will be sliced if word's length longer than `length`.   * see issue #23 for more details   */trimTheOnlyWord:boolean/**   * keep whitespaces, by default continuous paces will   *  be replaced with one space, set it true to keep them   */keepWhitespaces:boolean}/** * options interface for function */typeIOptions=Partial<IFullOptions>functiontruncate(html:string|CheerioAPI,length?:number|IOptions,truncateOptions?:IOptions):string// and truncate.setup to change default optionstruncate.setup(options:IOptions):void

Default options

{stripTags:false,ellipsis:'...',decodeEntities:false,excludes:'',byWords:false,reserveLastWord:false,trimTheOnlyWord:false,keepWhitespaces:false}

truncate.setup({stripTags:true,length:10})truncate('<p><img src="xxx.jpg">Hello from earth!</p>')// => Hello from

import*ascheeriofrom'cheerio'truncate.setup({stripTags:true,length:10})// truncate option `decodeEntities` will not work//    you should config it in cheerio options by yourselfconst$=cheerio.load('<p><img src="xxx.jpg">Hello from earth!</p>',{/** set decodeEntities if you need it */decodeEntities:true/* any cheerio instance options*/},false)// third parameter is for `isDocument` option, set to false to get rid of extra wrappers, see cheerio's doc for detailstruncate($)// => Hello from

Notice

Typescript support

importtruncate,{typeIOptions}from'truncate-html'consthtml='<p><img src="abc.png"><i>italic<b>bold</b></i>This is a string</p> for test.'constoptions:IOptions={length:10,byWords:true}truncate(html,options)// => <p><img src="abc.png"><i>italic<b>bold...</b></i></p>

custom node truncate strategy

importtruncate,{typeIOptions,typeICustomNodeStrategy}from'truncate-html'// argument node is a cheerio instanceconstcustomNodeStrategy:ICustomNodeStrategy=node=>{// remove img tagif(node.is('img')){return'remove'}// keep italic tag and its childrenif(node.is('i')){return'keep'}// truncate summary tag that inside details tag instead of details tagif(node.is('details')){returnnode.find('summary')}}consthtml='<div><img src="abc.png"><i>italic<b>bold</b></i><details><summary>Click me</summary><p>Some details</p></details>This is a string</div> for test.'constoptions:IOptions={length:10,  customNodeStrategy}truncate(html,options)// => <div><i>italic<b>bold</b></i><details><summary>Click me</summary><p>Some details</p></details>Th...</div>

About final string length

About html comments

About dealing with none alphabetic languages

Using existing cheerio instance

varhtml='<p><img src="abc.png">This is a string</p> for test.'const$=cheerio.load(`${html}`,{decodeEntities:true/** other cheerio options */},false)// third parameter is for `isDocument` option, set to false to get rid of extra wrappers, see cheerio's doc for detailstruncate($,10)

Examples

vartruncate=require('truncate-html')// truncate htmlvarhtml='<p><img src="abc.png">This is a string</p> for test.'truncate(html,10)// returns: <p><img src="abc.png">This is a ...</p>// truncate string with emojisvarstring='<p>poo 💩💩💩💩💩<p>'truncate(string,6)// returns: <p>poo 💩💩...</p>// with options, remove all tagsvarhtml='<p><img src="abc.png">This is a string</p> for test.'truncate(html,10,{stripTags:true})// returns: This is a ...// with options, truncate by words.//  if you try to truncate none alphabet language(like CJK)//      it will not act as you wishvarhtml='<p><img src="abc.png">This is a string</p> for test.'truncate(html,3,{byWords:true})// returns: <p><img src="abc.png">This is a ...</p>// with options, keep whitespacesvarhtml='<p>         <img src="abc.png">This is a string</p> for test.'truncate(html,10,{keepWhitespaces:true})// returns: <p>         <img src="abc.png">This is a ...</p>// combine length and optionsvarhtml='<p><img src="abc.png">This is a string</p> for test.'truncate(html,{length:10,stripTags:true})// returns: This is a ...// custom ellipsis signvarhtml='<p><img src="abc.png">This is a string</p> for test.'truncate(html,{length:10,ellipsis:'~'})// returns: <p><img src="abc.png">This is a ~</p>// exclude some special elements(by selector), they will be removed before counting content's lengthvarhtml='<p><img src="abc.png">This is a string</p> for test.'truncate(html,{length:10,ellipsis:'~',excludes:'img'})// returns: <p>This is a ~</p>// exclude more than one category elementsvarhtml='<p><img src="abc.png">This is a string</p><div> unwanted string inserted ( ´•̥̥̥ω•̥̥̥` ）</div> for test.'truncate(html,{length:20,stripTags:true,ellipsis:'~',excludes:['img','.something-unwanted']})// returns: This is a string for~// handing encoded charactersvarhtml='<p>&nbsp;test for &lt;p&gt; encoded string</p>'truncate(html,{length:20,decodeEntities:true})// returns: <p> test for &lt;p&gt; encode...</p>// when set decodeEntities falsevarhtml='<p>&nbsp;test for &lt;p&gt; encoded string</p>'truncate(html,{length:20,decodeEntities:false// this is the default value})// returns: <p>&nbsp;test for &lt;p...</p>// and there may be a surprise by setting `decodeEntities` to true  when handing CJK charactersvarhtml='<p>&nbsp;test for &lt;p&gt; 中文 string</p>'truncate(html,{length:20,decodeEntities:true})// returns: <p> test for &lt;p&gt; &#x4E2D;&#x6587; str...</p>// to fix this, see below for instructions// custom node strategy to keep some special elementsvarhtml='<p><img src="abc.png"><i>italic<b>bold</b></i>This is a string</p> for test.'truncate(html,{length:10,customNodeStrategy:node=>{if(node.is('img')){return'remove'}if(node.is('i')){return'keep'}}})// returns: <p><i>italic<b>bold</b></i>This is a ...</p>// custom node strategy to truncate summary instead of original nodevarhtml='<div><details><summary>Click me</summary><p>Some details</p></details>other things</div>'truncate(html,{length:10,customNodeStrategy:node=>{if(node.is('details')){returnnode.find('summary')}}})// returns: <div><details><summary>Click me</summary><p>Some details</p></details>ot...</div>

Credits