wp_tag_cloud() │ WP 2.3.0

Display tag cloud. The text size is set by the 'smallest' and 'largest' arguments, which will use the 'unit' argument value for the CSS text size unit. The 'format' argument can be 'flat' (default), 'list', or 'array'. The flat value for the 'format' argument will separate tags with spaces. The list value for the 'format' argument will format the tags in a UL HTML list. The array value for the 'format' argument will return in PHP array type format.

The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'. The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC'.

The 'number' argument is how many tags to return. By default, the limit will be to return the top 45 tags in the tag cloud list.

The 'topic_count_text' argument is a nooped plural from _n_noop() to generate the text for the tag link count.

The 'topic_count_text_callback' argument is a function, which given the count of the posts with that tag returns a text for the tag link count.

The 'post_type' argument is used only when 'link' is set to 'edit'. It determines the post_type passed to edit.php for the popular tags edit links.

The 'exclude' and 'include' arguments are used for the get_tags() function. Only one should be used, because only one will be used and the other ignored, if they are both set.

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.

Uses: wp_generate_tag_cloud()

Hooks from the function

wp_tag_cloud

Return

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

Usage

wp_tag_cloud( $args );

$args(array|string)

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.

Default: ''

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.
Default: first post type associated with the taxonomy
echo(true|false)
Whether or not to echo the return value.
Default: true

Examples

#1 What the function returns

wp_tag_cloud( 'smallest=8&largest=22' );

It displays it on the screen:

<a href="https://example.com/tag/ajax"
   class="tag-cloud-link tag-link-134 tag-link-position-1"
   style="font-size: 13.283018867925pt;" aria-label="AJAX (4 elements)">AJAX</a>

<a href="https://example.com/tag/chrome"
   class="tag-cloud-link tag-link-1603 tag-link-position-2"
   style="font-size: 8pt;" aria-label="Chrome (1 element)">Chrome</a>

<a href="https://example.com/tag/css" class="tag-cloud-link tag-link-531 tag-link-position-3"
   style="font-size: 13.283018867925pt;" aria-label="CSS (4 elements)">CSS</a>
	...

List:

wp_tag_cloud( [
	'format' => 'list',
] );

It will:

<ul class='wp-tag-cloud' role='list'>
	<li><a href="https://site.com/met/ajax" class="tag-cloud-link tag-link-134 tag-link-position-1" style="font-size: 13.283018867925pt;" aria-label="AJAX (4 elements)">AJAX</a></li>
	<li><a href="https://site.com/met/chrome" class="tag-cloud-link tag-link-1603 tag-link-position-2" style="font-size: 8pt;" aria-label="Chrome (1 elements)">Chrome</a></li>
	...
</ul>

#2 Basic usage

Let's display the tag cloud with the title "Popular Tags":

if ( function_exists( 'wp_tag_cloud' ) ){

	echo '<h2>Popular tags</h2>';

	wp_tag_cloud( 'smallest=8&largest=22' );
}

#3 Another example demonstrating the transmission of different parameters

Change the size of the tags (smallest=15&largest=40), limit the number of output tags (number=50), and sort them by the number of posts rather than by name (orderby=count):

<?php wp_tag_cloud( 'smallest=15&largest=40&number=50&orderby=count' ); ?>

#4 Get a list, not display it on the screen

Let's write the list in the $tag variable so that we can use it later in php for our own purposes:

$tag = wp_tag_cloud( 'format=array' );

print_r( $tag );

#5 Category Cloud

Let's display the category cloud instead of the tag cloud. To do this, let's change the name of the taxonomy:

<?php wp_tag_cloud( [ 'taxonomy' => 'category' ] ); ?>

#6 Tag and category cloud at the same time

You can put categories and tags into one cloud:

<?php
wp_tag_cloud( [
	'taxonomy' => [ 'post_tag', 'category' ],
] );
?>

#7 Changing the text of the title attribute of the `<a>` tag

When hovering over the link, the number of tag posts is shown. To change this text, you can use the parameter topic_count_text_callback, where we specify our function to create the text:

wp_tag_cloud( [
	'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 ) );
}

#8 Tag Archive

As one of the options for using tags, I suggest creating archive pages of tags. When you click on a certain tag, you will be taken to a page with posts associated with that tag. How such a page looks like is determined by the template file tag.php, if there is no such file (usually it is not), then the output generation is given to the file archives.php.

Let's make a tag page that will show a tag cloud at the beginning of the page, followed by the posts related to the selected tag. To do this, create (if you don't have one) or change (if you have one) the file tag.php. Create the file in the theme directory.

The contents of the tags.php file:

<?php
/*
Template Name: Tag Archive
*/
?>

<?php get_header(); ?>

<div>

	<h2>Tag Archive</h2>

	<?php wp_tag_cloud( '' ); ?>
	<div class="navigation">
		<div class="alignleft"><?php next_posts_link( '« Older Entries' ) ?></div>
		<div class="alignright"><?php previous_posts_link( 'Newer Entries »' ) ?></div>
	</div>
	<?php
	if( have_posts() ) {
		while( have_posts() ) {
			the_post();
			?>
			<h2>
				<a href="<?php the_permalink() ?>" rel="bookmark"
				   title="Permanent Link to <?php esc_attr( get_the_title() ) ?>"><?php the_title() ?></a>
			</h2>
			<div class="entry">
				<?php the_content( 'Read the rest of this entry »' ); ?>
			</div>
			<?php
		}
	}
	?>
</div>

<?php get_footer(); ?>

This example does not take CSS styles into account, so incompatibility with the template is possible.

#9 Changing the default settings for the tag cloud widget through the filter

Suppose we want to reduce the maximum font size for a tag cloud widget. We need to set 16 instead of 22 for largest. To do this, use the widget_tag_cloud_args hook.

add_filter( 'widget_tag_cloud_args', function( $args ){

	$args['largest'] = 16;

	return $args;
} );

#10 Get an OL list and add a class to the LI elements

We need to add a CSS class to the LI elements using the 'format' argument to make the links appear in an OL list instead of a UL list.

$cloud = wp_tag_cloud( [
	'format' => 'list',
	'echo' => false,
] );

$cloud = str_replace( [ '<ul ','</ul>' ], [ '<ol ','</ol>' ], $cloud );

$cloud = str_replace( '<li>', '<li class="cloud-li-class">', $cloud );

echo $cloud;

Result:

<ol class='wp-tag-cloud' role='list'>
	<li class="cloud-li-class"><a href="/met/ajax" class="tag-cloud-link tag-link-134 tag-link-position-1" style="font-size: 13.283018867925pt;" aria-label="AJAX (4 elements)">AJAX</a></li>
	<li class="cloud-li-class"><a href="/met/chrome" class="tag-cloud-link tag-link-1603 tag-link-position-2" style="font-size: 8pt;" aria-label="Chrome (1 item)">Chrome</a></li>
	...
</ol>

Changelog

Since 2.3.0	Introduced.
Since 2.8.0	Added the `taxonomy` argument.
Since 4.8.0	Added the `show_count` argument.

`wp_tag_cloud() wp tag cloud` code ^{WP 6.5.2}

wp-includes/category-template.php

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