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;
}

Hooks

apply_filters( ‘wp_tag_cloud’, string|string[] $return, array $args )

Filters the tag cloud output.

Changelog

VersionDescription
4.8.0Added the show_count argument.
2.8.0Added the taxonomy argument.
2.3.0Introduced.

User Contributed Notes

  1. Skip to note 12 content

    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 ) );
    	}
    ?>

You must log in before being able to contribute a note or feedback.