wp_tag_cloud() │ WP 2.3.0

Outputs or retrieves a tag cloud (a list of tags in the form of a cloud). You can specify any taxonomy.

To display elements of a custom taxonomy in the form of a cloud, specify the taxonomy name in the taxonomy parameter.

"Tag cloud" is called so because the size of the text for each tag depends on how many posts are associated with the tag. The more posts, the larger the tag text will be (resulting in something resembling a cloud).

Starting from version 2.8, the taxonomy parameter was added, allowing the creation of a cloud not only for standard tags but also for categories and custom taxonomies.

Uses: wp_generate_tag_cloud()

Hooks from the function

wp_tag_cloud

Returns

null|String|String[]. Outputs the HTML code of the list.

Returns HTML if the echo = false parameter is set.
Will return an array of the tag cloud if the format = array parameter is set.
false if it failed to retrieve tags.

Usage Template

wp_tag_cloud( [
	'smallest'  => 8,
	'largest'   => 22,
	'unit'      => 'pt',
	'number'    => 45,
	'format'    => 'flat',
	'separator' => "\n",
	'orderby'   => 'name',
	'order'     => 'ASC',
	'exclude'   => null,
	'include'   => null,
	'link'      => 'view',
	'taxonomy'  => 'post_tag',
	'echo'      => true,
	'topic_count_text_callback' => 'default_topic_count_text',
] );

Usage

<?php wp_tag_cloud( $args ); ?>

$args(string/array): Arguments based on which the list will be built.
Default: base values

Arguments of the $args parameter

In $args, you can also specify all parameters of the function wp_generate_tag_cloud() and get_terms().

smallest(int)

The text size for tags with the smallest number of posts (units are specified in the unit parameter).
Default: 8

largest(int)

The text size for tags with the largest number of posts (units are specified in the unit parameter).
Default:

unit(string)

Units of measurement for the smallest and largest parameters. Can be any CSS size type: pt, px, em, %.
Default: 'pt'

number(int)

The maximum number of tags to be displayed in the list. If set to 0, all tags will be shown without limitation.
Default: 45

format(string)

In what format to output the list. Can be:

flat - tags will be separated by the separator specified in the separator parameter;
list - UL list with CSS class 'wp-tag-cloud';
array - will return the tag cloud in an array for further processing in PHP.
Default: 'flat'

separator(string)

Text between tags.
Default: "\n"

orderby(string)

Sort tags by name (name) or number of posts (count). Does not affect the database query.
Default: 'name'

order(string)

Sorting order. Can be:

ASC - in order (1,2,3);
DESC - in reverse order (3,2,1);
RAND - random order (shuffle).

order and orderby do not affect the database query. Tags are first retrieved from the database, then sorted. These parameters for retrieving from the database are equal to: orderby=count and order=DESC and cannot be changed.
Default: 'ASC'

exclude(string)

Exclude specified tags. IDs should be specified as a comma-separated list.
Default: null

include(string)

Show only specified tags. IDs should be specified as a comma-separated list.
Default: null

topic_count_text_callback(string/array)

A function that receives the number of posts and returns text for the tag. You can set your own function if you need to display some other text with the number of posts for each tag.
Default: default_topic_count_text

link(string)

Where the tag link will lead.

view - clicking on the tag will take you to the tag page;
edit - clicking on the tag will take you to the tag editing page.
Default: view

taxonomy(string/array)

The name of the taxonomy or an array of several names from which the cloud will be built. Can be:

post_tag;
category;
link_category;
Custom taxonomy;
Array of taxonomy names - parameter introduced in version 3.1.
Default: post_tag

show_count(boolean)

Show the number of posts in the tag. Default is 0. Can be: 0, 1 or true/false. Since WP 4.8.

echo(boolean)

1 - Output to the screen, 0 - return result for further processing.
Default: 1 (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.9.1}

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