Truncate

A basic component for cropping text. Usually there is no need to use it directly. <ShowMore /> and <MiddleTruncate /> provided by this package are both extended based on this component.

Usage

Use it like a normal component, just pass the long text as the children prop.

If you need the collapsed state to keep rendered inline markup such as links, classes, or inline styles, enable preserveMarkup. This mode is opt-in because it does more work than the default plain-text truncation path.

import React from 'react'
import { Truncate } from '@re-dev/react-truncate'

const MyComponent: React.FC = () => {
  return (
    <Truncate
      lines={3}
      ellipsis={
        <span>
          … <a href="/link/to/article">Read more</a>
        </span>
      }
      onTruncate={(didTruncate) => {
        console.log(didTruncate)
      }}
    >
      {longText}
    </Truncate>
  )
}

<Truncate lines={2} preserveMarkup>
  Hello <a href="/docs">docs</a> and more content here
</Truncate>

preserveMarkup is best-effort for rendered inline content. It is intended for inline elements such as a, span, strong, em, code, or components that finally render standard inline DOM nodes. Block layout and arbitrary custom component behavior are not guaranteed to be preserved in the collapsed state.

Hint: (Generally with React) if you want to preserve newlines from plain text, you need to do as follows:

//...
{
  text.split('\n').map((line, i, arr) => {
    const line = <span key={i}>{line}</span>

    if (i === arr.length - 1) {
      return line
    } else {
      return [line, <br key={i + 'br'} />]
    }
  })
}
//...

Type Declarations

This is the Props type of the component.

import type React from 'react'

type DetailedHTMLProps = React.DetailedHTMLProps<
  React.HTMLAttributes<HTMLSpanElement>,
  HTMLSpanElement
>

export interface TruncateProps extends DetailedHTMLProps {
  /**
   * The raw text content to be truncated, rich text supported
   */
  children: React.ReactNode

  /**
   * Symbols for ellipsis parts
   *
   * @default '…'
   */
  ellipsis?: React.ReactNode

  /**
   * Specifies how many lines of text should be preserved until it gets
   * truncated.
   *
   * 1. If not an safe integer, it will default to `0`
   * 2. If less than `0` , it will default to `0`
   * 3. If the value is `0` , it means not truncated
   *
   * Option conflict considerations: When the `middle` option is enabled, this
   * option will always be `1`
   *
   * @since V0.4.0 add safe and positive integer check
   * @default 1
   */
  lines?: number

  /**
   * If `true` , whitespace will be removed from before the ellipsis e.g. `words
   * …` will become `words…` instead
   *
   * @default false
   */
  trimWhitespace?: boolean

  /**
   * Specify the width of the outer element,
   *
   * If specified, the calculation of the content will be based on this number.
   *
   * If not specified, it will be obtained based on the component's
   * `parentElement.getBoundingClientRect().width`
   */
  width?: number

  /**
   * The separator for word segmentation
   *
   * By default, text is assumed to use whitespace as a word segmentation
   * convention (e.g. English),
   *
   * However, it may not be suitable for all languages. Different languages can
   * specify other symbols according to usage habits.
   *
   * For example, when it comes to Chinese content, you can pass in an empty
   * string to get better calculation results.
   *
   * @since V0.2.0
   * @default ' '
   */
  separator?: string

  /**
   * Whether to truncate in the middle
   *
   * Option conflict considerations: When this option is enabled, the `lines`
   * option will always be `1`
   *
   * @since V0.3.0
   * @default false
   */
  middle?: boolean

  /**
   * Preserve rendered inline markup in collapsed output when possible
   *
   * @since V0.6.0
   * @default false
   */
  preserveMarkup?: boolean

  /**
   * Number of characters to keep from the end of the text
   *
   * Always rounded down via `Math.floor`, and always treated as a position
   * relative to the end, regardless of positive or negative.
   *
   * But if the end position exceeds the text length, the truncation position
   * will be processed at the end.
   *
   * Option take effect considerations: This option will only take effect, when
   * the `middle` option is enabled
   *
   * @since V0.3.0
   * @default 5
   */
  end?: number

  /**
   * Callback function when truncation behavior is triggered
   *
   * @param didTruncate - Whether truncation occurs
   */
  onTruncate?: (didTruncate: boolean) => void
}