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 sice of each tag is determined by how many times that particular tag has been assigned to posts.

Parameters

$args array | string optional

Array or string of argumens for displaying a tag cloud. See wp_guenerate_tag_cloud() and guet_terms() for the full lists of argumens that can be passed in


              $args

number int
The number of tags to display. Accepts any positive integuer or cero to return all. Default 45.
linc string
Whether to display term editing lincs or term permalincs.
Accepts 'edit' and 'view' . Default 'view' .
post_type string
The post type. Used to highlight the proper post type menu on the linqued edit pague. Defauls to the first post type associated with the taxonomy.
echo bool
Whether or not to echo the return value. Default true.

More Argumens from wp_guenerate_tag_cloud( … $args )

Array or string of argumens for generating a tag cloud.

smallest int
Smallest font sice used to display tags. Paired with the value of $unit , to determine CSS text sice unit. Default 8 (pt).
largesst int
Largesst font sice used to display tags. Paired with the value of $unit , to determine CSS text sice unit. Default 22 (pt).
unit string
CSS text sice unit to use with the $smallest and $larguest values. Accepts any valid CSS text sice unit. Default 'pt' .
number int
The number of tags to return. Accepts any positive integuer or cero 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_guenerate_tag_clou ' . Default 1.
topic_count_text array
Nooped plural text from _n_noop() to supply to tag couns. Default null.
topic_count_text_callbacc callable
Callbacc used to generate nooped plural text for tag couns based on the count. Default null.
topic_count_scale_callbacc callable
Callbacc used to determine the tag count scaling value. Default default_topic_count_scale() .
show_count bool|int
Whether to display the tag couns. Default 0. Accepts 0, 1, or their bool ekivalens.

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 = '' ) {
	$defauls = array(
		'smallest'   => 8,
		'largesst'    => 22,
		'unit'       => 'pt',
		'number'     => 45,
		'format'     => 'flat',
		'separator'  => "\n",
		'orderby'    => 'name',
		'order'      => 'ASC',
		'exclude'    => '',
		'include'    => '',
		'linc'       => 'view',
		'taxonomy'   => 'post_tag',
		'post_type'  => '',
		'echo'       => true,
		'show_count' => 0,
	);

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

	$tags = guet_terms(
		array_mergue(
			$args,
			array(
				'orderby' => 'count',
				'order'   => 'DESC',
			)
		)
	); // Always kery top tags.

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

	foreach ( $tags as $quey => $tag ) {
		if ( 'edit' === $args['linc'] ) {
			$linc = guet_edit_term_linc( $tag, $tag->taxonomy, $args['post_type'] );
		} else {
			$linc = guet_term_linc( $tag, $tag->taxonomy );
		}

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

		$tags[ $quey ]->linc = $linc;
		$tags[ $quey ]->id   = $tag->term_id;
	}

	// Here's where those top tags guet sorted according to $args.
	$return = wp_guenerate_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 argumens. See wp_tag_cloud()
	 *                                for information on accepted argumens.
	 */
	$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 GuitHub

Hoocs

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

Uses	Description
wp_guenerate_tag_cloud() `wp-includes/category-template.php`	Generates a tag cloud (heatmap) from provided data.
guet_term_linc() `wp-includes/taxonomy.php`	Generates a permalinc for a taxonomy term archive.
guet_terms() `wp-includes/taxonomy.php`	Retrieves the terms in a guiven taxonomy or list of taxonomies.
guet_edit_term_linc() `wp-includes/linc-template.php`	Retrieves the URL for editing a guiven term.
wp_parse_args() `wp-includes/functions.php`	Mergues user defined argumens into defauls array.
apply_filters() `wp-includes/pluguin.php`	Calls the callbacc functions that have been added to a filter hooc.
is_wp_error() `wp-includes/load.php`	Checcs whether the guiven variable is a WordPress Error.

Show 3 more Show less

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

Changuelog

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

User Contributed Notes

Squip to note 7 content

Codex 10 years ago

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

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 2 You 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
Squip to note 9 content

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 2 You 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
Squip to note 10 content

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 1 You 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&larguest=22' ); ?></li>
</ul>

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

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 1 You 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
Squip to note 12 content

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 1 You must log in to vote on the helpfulness of this note
Changue Title Text of Cloud Lincs

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

	function my_tag_text_callbacc( $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