Understanding and Using the WordPress wp_tag_cloud() function

15 Jun 2012 By Articles No Comments

In a nutshell the WordPress wp_tag_cloud() function is the main built-in function that will display your recent post tags as a tag cloud. Your tags are listed in various ways and sizes determined by the amount of times that certain tag is used.

Understanding the wp_tag_cloud() function and it’s attributes

As previously mentioned this is the main functions that displays the tags that you have set up in your WordPress site. The function has a great deal off attributes that we can use when displaying our tag cloud.

Creating your Post Tags

Creating your Post Tags

Creating your Post Tags

When we create a new post in the WordPress Dashboard we have a meta box usually in the right hand column where you can add certain tags for the post you are writing. You can also click the link that states “Choose from the most used tags” which will display a list of your poplar tags that you have been using.

Managing our Post Tags

Managing our Post Tags

We can manage our post tags by navigating to the “Tags” link found under the “Posts” menu in the left column of the WordPress Dashboard.

Once we navigate to the tag management page we are presented with different sections and management options. Firstly in the top left column we have out “Popular” tags listed.

Directly under this tag cloud we have the fields to manually add new tags. To add a new tag we add  the name, the tag slug and a description as well if you desire. When creating tags through the “New Post” page the slug is automatically created, however if adding one through the management page it is not so you will have to add your own. Remember not to use spaces. Separate spaces with hyphens.

In the right hand column of the page we have all our tags listed that are being used throughout the site. This is where we can manage our tags. We can see the name, description, slug and amount of posts tat that certain tag is being utilized in.

On the WPInsite website I have the option for visitors to make Guest Posts so I like to frequently visit this page and delete all the spam tags and tags that are not being used in any posts. When guests create posts they are giving the option to add their own post tags.

Displaying your Post Tags using the wp_tag_cloud() function

Now, onto the part of displaying our tag cloud on the front of our site. We have a couple of options here to display our tags:

  1. Through the “Tag Cloud” built-in WordPress widget.
  2. Insert directly into our theme files using the wp_tag_cloud()  function.

Displaying the tag cloud using the build in “Tag Cloud” widget

This is the easiest way to instantly create and display our tag cloud. If we navigate to the “Widgets” page which is a sub-menu of the “Appearance” menu we will see our “Tag Cloud” widget” in the list of available widgets.

Displaying the tag cloud using the build in "Tag Cloud" widget

Displaying the tag cloud using the build in “Tag Cloud” widget

To use this widget it is a simple matter of dragging the “Tag Cloud” widget over to one of our predefined sidebars where it will expand as per the above image. The usage here is simple. Add a title for the widget and then select the Taxonomy. The Taxonomy options you have here are:

  • Tags
  • Categories

That’s it for this option fill in the details and click the “save” button.

Displaying the tag cloud in our theme files using the wp_tag_cloud() function

This is the core of of topic here and before we go onto how to use the wp_tag_cloud() function. We first need to understand its attributes to be able to adequately use it to it’s full potential.

The most basic usage for this function is as follows:

<?php wp_tag_cloud( $args ); ?>
<?php wp_tag_cloud( $args ); ?>

Now, the the wp_tag_cloud() function is awesome in the fact that it has so many parameters that we can use. Lets spend a moment listing those parameters.

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

Getting a grasp on what all these parameters mean and how to use them makes the displaying of the tag cloud so amazing.

The wp_tag_cloud() Parameters

smallest – (integer) (optional)
The text size of the tag with the smallest count value (units given by unit parameter). You can give this any value you want.
Default: 8

largest – (integer) (optional)
The text size of the tag with the highest count value (units given by the unit parameter). You can give this any value you want.
Default: 22

unit – (string) (optional)
The Unit of measure as pertains to the smallest and largest values. This can be any CSS length value, e.g. pt, px, em, %.
Default: ‘pt’

number – (integer) (optional)
The number of actual tags to display in the cloud. (Use ‘0’ to display all tags.) This will depend on how much space you have allocated in your theme to display the tag cloud.
Default: 45

format – (string) (optional)
Format of the cloud display.

  • ‘flat’ separated by whitespace defined by ‘separator’ parameter.
  • ‘list’ UL with a class of ‘wp-tag-cloud’
  • ‘array’ returns the tag cloud as an array for use in PHP

Default: flat

separator – (string) (optional)
The text/space between tags.
Default: ‘\n’ (whitespace)

orderby – (string) (optional)
Order of the tags.

  • ‘name’
  • ‘count’

Default: name

order – (string) (optional)
Sort order.

  • ‘ASC’
  • ‘DESC’
  • ‘RAND’ tags are in a random order.

Default: ASC

exclude – (string) (null optional)
Default: None

include – (string) (null optional)
Default: None

topic_count_text_callback – (string) (optional)
The function, which, given the count of the posts with that tag, returns a text for the tooltip of the tag link.
Default: default_topic_count_text

link – (string) (optional)
Set link to allow edit of a particular tag.

  • ‘view’
  • ‘edit’

Default: view

taxonomy – (string or array) (optional)
Taxonomy or array of taxonomies to use in generating the cloud.

  • ‘post_tag’
  • ‘category’
  • ‘link_category’
  • ‘any other registered taxonomy’
  • or array of taxonomies Note: this parameter was introduced with Version 3.1

Default: post_tag

echo – (boolean) (optional)
Display the result or return it in a variable.

  • 1 (true)
  • 0 (false)

Default: true (display the tag cloud).

Before moving on to how to display your tag cloud, make sure you do read and get a grasp of what each of the above parameters mean and their values, because without that knowledge you cannot display the tag cloud to your exact liking.

Displaying the wp_tag_cloud()

The first thing you want to do is navigate to your theme directory “wp-content/themes/your-current-theme” and open up the file in wish you want to display your tag cloud. For purposes of demonstration lets say we open up our “sidebar.php” file and want to manually add our own tag cloud.

We will know demonstrate some example and usage in using this very powerful WordPress function. In your “sidebar.php” file browse to where you want to display the tag cloud and try some of the following examples by adding the following code.

Once important point to mention here is that the wp_tag_cloud() is very flexible in the fact that you can add the parameters or arguments in either array form or simply inline separated by the & symbol.

Example 1: Separating arguments by & symbol

This example demonstrates how to display all our arguments in one simple long inline string.

<?php wp_tag_cloud('smallest=15&largest=40&unit=px&number=25&separator=:: &orderby=count&order=RAND'); ?>
<?php wp_tag_cloud('smallest=15&largest=40&unit=px&number=25&separator=:: &orderby=count&order=RAND'); ?>

Example 2: Separating arguments in array format

We will now demonstrate how to display the same wp_tag_cloud() query in array format.

<?php wp_tag_cloud( array( 'smallest' => '15' ,'largest' => '40', 'unit' => 'px', 'number' => '25', 'separator' => ':: ', 'orderby' => 'count', 'order' => 'RAND') ); ?>
<?php wp_tag_cloud( array( 'smallest' => '15' ,'largest' => '40', 'unit' => 'px', 'number' => '25', 'separator' => ':: ', 'orderby' => 'count', 'order' => 'RAND') ); ?>

The output of both these queries is exactly the same as pictured below.

Simple tag cloud with custom smallest and largest font sizes

<?php wp_tag_cloud('smallest=12&largest=30'); ?>
<?php wp_tag_cloud('smallest=12&largest=30'); ?>

Return the wp_tag_cloud() as an array but do not display it

We can return the tag cloud as an array in our code so that later on down the page we can display it using PHP code.

<?php $tag = wp_tag_cloud('format=array' );?>
<?php $tag = wp_tag_cloud('format=array' );?>

Display a custom Taxonomy cloud cloud

By using the Taxonomy argument we can either display the default ‘post_tags‘, ‘category‘ taxonomy or any custom post types that you have set up in your theme. Lets demonstrate how to display a tag cloud for our custom “Portfolio” post type.

<?php wp_tag_cloud( array( 'taxonomy' => 'portfolio' ) );?>
<?php wp_tag_cloud( array( 'taxonomy' => 'portfolio' ) );?>


As you can see the wp_tag_cloud() is a very powerful and useful function that we can easily use in a variety of ways. Don’t be scared to experiment in your theme files with the wp_tag_cloud() function and change the tag cloud to your custom design.

Be sure to check out our other great WordPress Articles and Plugins
Enjoy this article? If so, we would love to hear your thoughts in the comments below


Related Blog Posts

Leave a Reply