wp_trim_words() – Function | Developer.WordPress.org

Trims text to a certain number of words.

Description

This function is localized. For languages that count ‘words’ by the individual character (such as East Asian languages), the $num_words argument will apply to the number of individual characters.

Parameters

$textstringrequired: Text to trim.
$num_wordsintoptional: Number of words.
Default:55
$morestringoptional: What to append if $text needs to be trimmed. Default '…'.
Default:null

Return

string Trimmed text.

Source

function wp_trim_words( $text, $num_words = 55, $more = null ) {	if ( null === $more ) {	$more = __( '&hellip;' );	}	$original_text = $text;	$text = wp_strip_all_tags( $text );	$num_words = (int) $num_words;	if ( str_starts_with( wp_get_word_count_type(), 'characters' ) && preg_match( '/^utf\-?8$/i', get_option( 'blog_charset' ) ) ) {	$text = trim( preg_replace( "/[\n\r\t ]+/", ' ', $text ), ' ' );	preg_match_all( '/./u', $text, $words_array );	$words_array = array_slice( $words_array[0], 0, $num_words + 1 );	$sep = '';	} else {	$words_array = preg_split( "/[\n\r\t ]+/", $text, $num_words + 1, PREG_SPLIT_NO_EMPTY );	$sep = ' ';	}	if ( count( $words_array ) > $num_words ) {	array_pop( $words_array );	$text = implode( $sep, $words_array );	$text = $text . $more;	} else {	$text = implode( $sep, $words_array );	}	/** * Filters the text content after words have been trimmed. * * @since 3.3.0 * * @param string $text The trimmed text. * @param int $num_words The number of words to trim the text to. Default 55. * @param string $more An optional string to append to the end of the trimmed text, e.g. &hellip;. * @param string $original_text The text before it was trimmed. */	return apply_filters( 'wp_trim_words', $text, $num_words, $more, $original_text ); }

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_trim_words’, string $text, int $num_words, string $more, string $original_text ): Filters the text content after words have been trimmed.

Uses	Description
wp_strip_all_tags()`wp-includes/formatting.php`	Properly strips all HTML tags including ‘script’ and ‘style’.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_option()`wp-includes/option.php`	Retrieves an option value based on an option name.

Show 1 more Show less

Used by	Description
WP_REST_Block_Directory_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php`	Parse block metadata for a block, and prepare it for an API response.
WP_Customize_Nav_Menu_Item_Setting::value_as_wp_post_nav_menu_item()`wp-includes/customize/class-wp-customize-nav-menu-item-setting.php`	Get the value emulated into a WP_Post and set up as a nav_menu_item.
wp_dashboard_recent_drafts()`wp-admin/includes/dashboard.php`	Show recent drafts of the user on the dashboard.
wp_trim_excerpt()`wp-includes/formatting.php`	Generates an excerpt from the content, if needed.
wp_widget_rss_output()`wp-includes/widgets.php`	Displays the RSS entries in a list.
wp_setup_nav_menu_item()`wp-includes/nav-menu.php`	Decorates a menu item object with the shared navigation menu item properties.
get_comment_excerpt()`wp-includes/comment-template.php`	Retrieves the excerpt of the given comment.

Show 2 more Show less

Changelog

Version	Description
3.3.0	Introduced.

User Contributed Notes

Skip to note 6 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note
An example which strips formatting:
```
<?php echo wp_trim_words( get_the_content(), 40, '...' ); ?>
```
Log in to add feedback
Skip to note 7 content

mymonoo 7 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
This function is useful for trimming overflow text. I used for displaying trimmed title in a fixed height div on smaller screens. This is just one line of code.. :)
```
<?php echo wp_trim_words( get_the_title(), 15 ); ?>
```
Log in to add feedback
Skip to note 8 content

Jb Audras 7 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Note: wp_trim_words() works with any text string:
```
$text = 'Some very long text'; $words = 20; $more = ' […]'; $excerpt = wp_trim_words( $text, $words, $more );
```
Log in to add feedback
Skip to note 9 content

Jb Audras 7 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Example: display comment excerpt in a comments custom query.
```
$args = array(	'number' => 3, ); $comments_query = new WP_Comment_Query; $comments = $comments_query->query( $args ); if ( $comments ) {	foreach ( $comments as $comment ) {	echo wp_trim_words( $comment->comment_content, 20, ' […]' );	} }
```
Log in to add feedback

tripflex 7 years ago

-1

If for some reason you need the words that were trimmed, here’s a modified version of this function, to return the words before AND after in an array:

if( ! function_exists( 'smyles_wp_split_words' ) ){	/** * Split a string based on word count * * This is similar to WordPress wp_trim_words function, but instead of just trimming after a certain amount of * words, this function returns an array with 'before' and 'after' keys -- providing you the string of text up * to the number of words (in before key), and the words after (in the after key). After key will be empty string * if there are less words in the passed string than number of words to split on. * * * @param string $text * @param int $num_words * * @return array Array with `before` and `after` keys. The `before` key contains all words up to $num_words, the * `after` key contains the words after $num_words (or empty string if passed string has less words * than passed in $text) * */	function smyles_wp_split_words( $text, $num_words = 55 ) {	$text = wp_strip_all_tags( $text );	/* * translators: If your word count is based on single characters (e.g. East Asian characters), * enter 'characters_excluding_spaces' or 'characters_including_spaces'. Otherwise, enter 'words'. * Do not translate into your own language. */	if ( strpos( _x( 'words', 'Word count type. Do not translate!' ), 'characters' ) === 0 && preg_match( '/^utf\-?8$/i', get_option( 'blog_charset' ) ) ) {	$text = trim( preg_replace( "/[\n\r\t ]+/", ' ', $text ), ' ' );	preg_match_all( '/./u', $text, $words_array_matches );	$words_array = $words_array_matches[0];	$sep = '';	} else {	$words_array = preg_split( "/[\n\r\t ]+/", $text, -1, PREG_SPLIT_NO_EMPTY );	$sep = ' ';	}	if ( count( $words_array ) > $num_words ) {	$before = implode( $sep, array_slice( $words_array, 0, $num_words ) );	$after = implode( $sep, array_slice( $words_array, $num_words, count( $words_array ) - 1 ) );	} else {	$before = implode( $sep, $words_array );	}	$results = array(	'before' => $before,	'after' => isset( $after ) ? $after : ''	);	return $results;	} }

https://gist.github.com/tripflex/5ccb97ac0b76d355bceff5111803d7ea

wp_trim_words( string $text, int $num_words = 55, string $more = null ): string

In this article