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

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.

Related

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 moreShow 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

1. Skip to note 7 content
   Codex 11 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
2. Skip to note 8 content
   Codex 11 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
3. Skip to note 9 content
   Codex 11 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
4. Skip to note 10 content
   Codex 11 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
5. Skip to note 11 content
   Codex 11 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
6. Skip to note 12 content
   Codex 11 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