wp_tag_cloud() – Function | Developer.WordPress.org

Displays a tag cloud.

Description

Outputs a list of tags in what is called a ‘tag cloud’, where the size of each tag is determined by how many times that particular tag has been assigned to posts.

Parameters

$argsarray|stringoptional

Array or string of arguments for displaying a tag cloud. See wp_generate_tag_cloud() and get_terms() for the full lists of arguments that can be passed in $args.

number int
The number of tags to display. Accepts any positive integer or zero to return all. Default 45.
link string
Whether to display term editing links or term permalinks.
Accepts 'edit' and 'view'. Default 'view'.
post_type string
The post type. Used to highlight the proper post type menu on the linked edit page. Defaults to the first post type associated with the taxonomy.
echo bool
Whether or not to echo the return value. Default true.

More Arguments from wp_generate_tag_cloud( … $args )

Array or string of arguments for generating a tag cloud.

smallest int
Smallest font size used to display tags. Paired with the value of $unit, to determine CSS text size unit. Default 8 (pt).
largest int
Largest font size used to display tags. Paired with the value of $unit, to determine CSS text size unit. Default 22 (pt).
unit string
CSS text size unit to use with the $smallest and $largest values. Accepts any valid CSS text size unit. Default 'pt'.
number int
The number of tags to return. Accepts any positive integer or zero to return all.
Default 0.
format string
Format to display the tag cloud in. Accepts 'flat' (tags separated with spaces), 'list' (tags displayed in an unordered list), or 'array' (returns an array).
Default 'flat'.
separator string
HTML or text to separate the tags. Default "n" (newline).
orderby string
Value to order tags by. Accepts 'name' or 'count'.
Default 'name'. The 'tag_cloud_sort' filter can also affect how tags are sorted.
order string
How to order the tags. Accepts 'ASC' (ascending), 'DESC' (descending), or 'RAND' (random). Default 'ASC'.
filter int|bool
Whether to enable filtering of the final output via 'wp_generate_tag_cloud'. Default 1.
topic_count_text array
Nooped plural text from _n_noop() to supply to tag counts. Default null.
topic_count_text_callback callable
Callback used to generate nooped plural text for tag counts based on the count. Default null.
topic_count_scale_callback callable
Callback used to determine the tag count scaling value. Default default_topic_count_scale() .
show_count bool|int
Whether to display the tag counts. Default 0. Accepts 0, 1, or their bool equivalents.

Default:''

Return

void|string|string[] Void if 'echo' argument is true, or on failure. Otherwise, tag cloud as a string or an array, depending on 'format' argument.

Source

function wp_tag_cloud( $args = '' ) {
	$defaults = array(
		'smallest'   => 8,
		'largest'    => 22,
		'unit'       => 'pt',
		'number'     => 45,
		'format'     => 'flat',
		'separator'  => "\n",
		'orderby'    => 'name',
		'order'      => 'ASC',
		'exclude'    => '',
		'include'    => '',
		'link'       => 'view',
		'taxonomy'   => 'post_tag',
		'post_type'  => '',
		'echo'       => true,
		'show_count' => 0,
	);

	$args = wp_parse_args( $args, $defaults );

	$tags = get_terms(
		array_merge(
			$args,
			array(
				'orderby' => 'count',
				'order'   => 'DESC',
			)
		)
	); // Always query top tags.

	if ( empty( $tags ) || is_wp_error( $tags ) ) {
		return;
	}

	foreach ( $tags as $key => $tag ) {
		if ( 'edit' === $args['link'] ) {
			$link = get_edit_term_link( $tag, $tag->taxonomy, $args['post_type'] );
		} else {
			$link = get_term_link( $tag, $tag->taxonomy );
		}

		if ( is_wp_error( $link ) ) {
			return;
		}

		$tags[ $key ]->link = $link;
		$tags[ $key ]->id   = $tag->term_id;
	}

	// Here's where those top tags get sorted according to $args.
	$return = wp_generate_tag_cloud( $tags, $args );

	/**
	 * Filters the tag cloud output.
	 *
	 * @since 2.3.0
	 *
	 * @param string|string[] $return Tag cloud as a string or an array, depending on 'format' argument.
	 * @param array           $args   An array of tag cloud arguments. See wp_tag_cloud()
	 *                                for information on accepted arguments.
	 */
	$return = apply_filters( 'wp_tag_cloud', $return, $args );

	if ( 'array' === $args['format'] || empty( $args['echo'] ) ) {
		return $return;
	}

	echo $return;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_tag_cloud’, string|string[] $return, array $args ): Filters the tag cloud output.

Uses	Description
wp_generate_tag_cloud()`wp-includes/category-template.php`	Generates a tag cloud (heatmap) from provided data.
get_term_link()`wp-includes/taxonomy.php`	Generates a permalink for a taxonomy term archive.
get_terms()`wp-includes/taxonomy.php`	Retrieves the terms in a given taxonomy or list of taxonomies.
get_edit_term_link()`wp-includes/link-template.php`	Retrieves the URL for editing a given term.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.

Show 3 more Show less

Used by	Description
WP_Widget_Tag_Cloud::widget()`wp-includes/widgets/class-wp-widget-tag-cloud.php`	Outputs the content for the current Tag Cloud widget instance.

Changelog

Version	Description
4.8.0	Added the `show_count` argument.
2.8.0	Added the `taxonomy` argument.
2.3.0	Introduced.

User Contributed Notes

Skip to note 7 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Cloud limited in size and ordered by count rather than name
```
<?php wp_tag_cloud( 'smallest=15&largest=40&number=50' ); ?>
```
Log in to add feedback
Skip to note 8 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Cloud returned as array but not displayed

The variable $tag will contain the tag cloud for use in other PHP code
```
 <?php $tag = wp_tag_cloud( 'format=array' ); ?>
```
Log in to add feedback
Skip to note 9 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Display a Cloud of Categories and Tags

Use the array feature of the taxonomy argument to cause a cloud of categories and tags to display.
```
<?php 
	$args = array(
		'taxonomy' => array( 'post_tag', 'category' ), 
	); 

	wp_tag_cloud( $args );
?>
```
Log in to add feedback
Skip to note 10 content

Codex 10 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
Cloud displayed under Popular Tags title
```
<?php if ( function_exists( 'wp_tag_cloud' ) ) : ?>

<h2>Popular Tags</h2>
<ul>
<li><?php wp_tag_cloud( 'smallest=8&largest=22' ); ?></li>
</ul>

<?php endif; ?>
```
Log in to add feedback
Skip to note 11 content

Codex 10 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
Display a Category Cloud

Use the taxonomy argument to cause a cloud of categories to display.
```
<?php wp_tag_cloud( array( 'taxonomy' => 'category' ) ); ?>
```
Log in to add feedback
Skip to note 12 content

Codex 10 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
Change Title Text of Cloud Links

Use the topic_count_text_callback argument to pass in a new callback function. The original function default_topic_count_text() is located in /wp-includes/category-template.php This example changes the title text from the default “topics” to “pictures”.
```
<?php 
	wp_tag_cloud( array( 'topic_count_text_callback' => 'my_tag_text_callback' ) ); 

	function my_tag_text_callback( $count ) {
		return sprintf( _n( '%s picture', '%s pictures', $count ), number_format_i18n( $count ) );
	}
?>
```
Log in to add feedback

wp_tag_cloud( array|string $args = '' ): void|string|string[]

In this article