@versini/ui-truncate

A lightweight and accessible React text truncation component built with TypeScript and TailwindCSS.

The Truncate component provides intelligent text truncation with toggle functionality for managing long text content. Perfect for article previews, descriptions, and any content that needs length management.

Table of Contents

• Features
• Installation
• Usage
• Rich Content Truncation

Features

• 🎯 Smart Truncation: Intelligent text truncation with customizable character limits
• 🔍 Expandable: Built-in expand/collapse toggle functionality
• ♿ Accessible: Screen reader friendly with proper button semantics
• 🌲 Tree-shakeable: Lightweight and optimized for bundle size
• 🔧 TypeScript: Fully typed with comprehensive prop definitions
• 🎭 Theme Support: Built-in support for light, dark, and system themes

Installation

npm install @versini/ui-truncate

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

import { Truncate } from "@versini/ui-truncate";

function App() {
  return (
    <Truncate length={100} mode="dark" focusMode="light">
      This is a very long text that needs to be truncated.
    </Truncate>
  );
}

Props

| Prop | Type | Default | Description | | ---------------------- | ----------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | The content to render. If not a string, it will be rendered as-is. | | length | number | 200 | The maximum number of characters to display before truncating. | | mode | "dark" \| "light" \| "system" \| "alt-system" | "system" | The mode of the button used for toggling truncated text. | | focusMode | "dark" \| "light" \| "system" \| "alt-system" | "system" | The focus mode of the button, affecting the focus ring's appearance. | | enableRichTruncation | boolean | false | When true, measures nested React content text and truncates it. Collapsed view is plain text (styling removed); expanded view restores full formatting. |

Example

import { Truncate } from "@versini/ui-truncate";

function App() {
  return (
    <div>
      <Truncate length={50} mode="light" focusMode="dark">
        Lorem ipsum dolor sit amet. Sed do ut labore et dolore magna aliqua. Sed
        do ut labore et dolore magna aliqua. Lorem ipsum dolor sit amet.
      </Truncate>
    </div>
  );
}

Behavior

• If the children prop is not a string, the component will render the children as-is without truncation.
• If the text exceeds the specified length, it will be truncated, and a button will appear to toggle between the truncated and full text.
• The button's appearance and focus ring can be customized using the mode and focusMode props.
• When enableRichTruncation is true, the component traverses nested React nodes, measures their combined textual content, and in the collapsed state renders a flattened plain text slice (no markup) so the toggle button appears immediately after the text. Expanding restores the original rich markup.

Rich Content Truncation

By default, only plain string children are truncated. Complex React node trees (e.g. with <strong>, <em>, or other inline components) are rendered in full to avoid unexpected structural changes.

If you need truncation that spans across nested elements, opt in with enableRichTruncation. Collapsed output is intentionally flattened to avoid layout shifts and orphaned inline elements; expanded output preserves original styling:

<Truncate length={80} enableRichTruncation>
  <p>
    <strong>Design systems</strong> help teams build consistent, accessible
    interfaces. They reduce duplication, improve quality, and accelerate
    delivery. <em>However</em>, maintaining them requires clear ownership and
    strong governance.
  </p>
</Truncate>

What happens when enabled:

• The textual content of all descendants is concatenated (whitespace preserved within text nodes)
• The truncation algorithm finds a word-aware boundary within the requested length
• Collapsed state: a flat plain-text slice is rendered (all markup removed)
• Expanded state: the original rich React node tree is rendered untouched
• The toggle button ("more..." / "less...") sits directly after the truncated text ensuring it stays on the same line when possible

Limitations / Notes:

• Collapsed view drops all formatting (no inline styles, marks, or semantic tags) by design
• If inline formatting splits a word across elements (e.g. <b>su</b><i>per</i>), truncation still respects word boundaries based on combined text
• Does not sanitize HTML; sanitize before passing any raw HTML via dangerouslySetInnerHTML
• Performance is O(N) over text nodes; suitable for typical UI fragments (< a few thousand characters)

License

MIT