Smart Trim
A field formatter that provides intelligent text trimming with more control than Drupal core's built-in "Summary or Trimmed" formatter.
smart_trim
Install
composer require 'drupal/smart_trim:^2.2'
composer require 'drupal/smart_trim:^2.1'
Overview
Smart Trim implements an enhanced field formatter for text fields (text, text_long, text_with_summary, string, and string_long) that significantly improves upon Drupal core's "Summary or Trimmed" formatter. It provides granular control over how text content is truncated for display in teasers, lists, and other condensed views.
The module intelligently handles HTML content during truncation, preserving valid markup structure while trimming to the specified length. It can trim by character count or word count, and includes sophisticated handling of word boundaries to avoid cutting words in half. When HTML is preserved, the module properly closes any open tags to maintain valid markup.
Smart Trim also provides optional "More" link functionality with extensive customization options including custom text, CSS classes, aria-label for accessibility, and the ability to open links in new windows. The module integrates with the Token module to allow dynamic values in link text and aria-labels.
For developers, Smart Trim offers Twig filters (smart_trim_chars and smart_trim_words) that can be used directly in templates, as well as a TruncateHTML service for programmatic text truncation. The module also provides a hook (hook_smart_trim_link_modify) to allow other modules to customize the "More" link.
Features
- Trim text by character count or word count with intelligent word boundary handling
- Configurable suffix (e.g., ellipsis) appended to trimmed text with Unicode support (\u2026)
- Optional "More" link with customizable text, CSS class, aria-label, and target window settings
- Strip HTML tags option that removes all HTML while preserving text content
- Preserve HTML option that maintains valid markup structure during truncation
- Summary field handling with options to use summary as-is, trim summary, or ignore summary
- Token replacement support in "More" link text and aria-label fields
- Twig filters (smart_trim_chars and smart_trim_words) for use in custom templates
- Theme template (smart-trim.html.twig) with extensive theme suggestions for customization
- Hook API (hook_smart_trim_link_modify) for programmatically modifying the "More" link
- Proper handling of HTML comments, figcaption, script, and style tags during stripping
- Automatic removal of trailing punctuation before appending suffix
- Zero-length trim option for hiding content entirely while showing summary
Use Cases
Creating Article Teasers
Configure the Body field on the Article content type's Teaser view mode to use Smart Trim. Set trim length to 300 characters with an ellipsis suffix (\u2026). Enable the More link with text 'Read more' and aria-label 'Read more about [node:title]' for accessibility. Enable 'Strip HTML' to ensure clean text output without embedded media or formatting affecting the layout.
Word-Based Trimming for Blog Posts
For blog listing pages where you want consistent teaser lengths regardless of word complexity, use word-based trimming. Set trim to 50 words to ensure each teaser provides roughly the same amount of content while maintaining readability.
Using Twig Filters in Custom Templates
In a custom node template, use the Twig filter to trim a field value directly: {{ content.field_description|render|smart_trim_chars(150, '...') }}. This is useful when you need trimming in contexts where the field formatter cannot be configured, such as custom blocks or complex layouts.
Conditional More Links
Enable 'Display More link only when content is trimmed' to prevent showing redundant Read More links on short content. This creates a cleaner interface where the link only appears when there is actually more content to read.
Accessibility-Enhanced Teasers
Configure the More link with a descriptive aria-label like 'Continue reading the full article about [node:title]' to provide screen reader users with context about where the link leads, rather than just hearing 'More' repeatedly.
Summary-Aware Display
For text_with_summary fields (like Body), configure summary handling to 'Use summary if present, and do not trim'. This respects author-provided summaries while falling back to automatic trimming when no summary exists.
Zero-Length Trim for Teasers
Use the 'Honor a zero trim length' option combined with a trim length of 0 to hide the body content entirely in a teaser while still displaying the More link. This is useful for listing pages where you only want titles and Read More links.
Tips
- Use \u2026 in the suffix field to display a proper ellipsis character (…) instead of three periods
- Override the smart-trim.html.twig template in your theme for complete control over output markup
- Use theme suggestions like smart_trim__node__article__body for field-specific customization
- The wrap_output option is deprecated; use template overrides instead for wrapping content
- Token replacement in More link text allows dynamic, context-aware link labels
- The TruncateHTML service can be injected into custom code for programmatic text truncation
- When using Twig filters, chain with |render first if the value might be a render array: {{ value|render|smart_trim_chars(100) }}
Technical Details
Hooks 1
hook_smart_trim_link_modify
Allows modules to modify the Smart Trim "More" link before it is rendered. This hook is invoked during field formatter rendering when a More link is displayed.
Troubleshooting 6
Ensure the entity has an ID (saved to database) and has a canonical link template. Inline Entity Form previews may not show the link. Also verify 'Display More link only when content is trimmed' is not enabled when content is not being trimmed.
This was fixed in version 2.1.1. Update to the latest version. The module now properly handles HTML entity decoding during the truncation process.
This was addressed in version 2.1.0. The module now adds spaces before opening tags before stripping to ensure words don't run together.
Use Unicode escape sequences in the suffix field. For example, use \u2026 for the ellipsis character (…). This was improved in version 2.1.1.
The More link text now uses config translation. Clear caches after updating and use the Configuration Translation interface to translate the values.
This was a bug fixed in version 2.2.0 where form states were only working for fields named 'body'. Update to the latest version.