WordPress : How to modify parameters of default Tag Cloud Widget

wordpress modifying parameters for tag- loud-widget thumbnail

Tag Cloud Widget gives visitors ability to browse different topics based on tags on your site. Recently I wanted to customize it a little for this site and assumed the widget itself would give you these settings, but you can only edit the most basic parameters. Instead of widgets, we can display the tag using WordPress function wp_tag_cloud in the template, which supports more parameters. But what if we want to use existing cloud tag widget? Luckily, there is a filter available that allows you to do that and is the topic of this article.

When we go to Dashboard > Appearance > Widgets, this is what we can edit in the WordPress default Tag Cloud widget. Only Title and Taxonomy can be changed:

WordPress tag cloud widget available settings

With wp_tag_cloud function, we can set many more parameters than what is offered in widget settings. It accepts $args array containing parameters for tag cloud customization. Here is a short list of what we can set:

  • smallest – text size of the smallest tag (the tag with lowest count)
  • largest - text size of the largest tag (the tag with highest count)
  • number – number of tags to display (default is 45, while 0 displays all the tags)
  • orderby - order the tags either by name (default) or count (‘name’, ’count’)
  • order – sort direction either ascending (default), descending or random (‘ASC’, ‘DESC’, ‘RAND’)

The problem with the wp_tag_cloud function is that it is used, when we want to add a tag cloud in the template file, but to set parameters for the already existing tag cloud added via widgets at Dashboard > Appearance > Widgets, we can't use this function.

Luckily, there is a filter available that can accept the same $args array parameters and apply it to an existing widget.

Solution - use the widget_tag_cloud_args filter to modify tag cloud widget parameters

WordPress has a widget_tag_cloud_args filter and is used to set taxonomy for a tag cloud widget. It accepts $args array and we can use that array to put other parameters in it.

Add the code below inside the functions.php file and put into $my_args array those parameters you want to modify. In the code below, we are changing smallest font size to 10, largest to 16 and tags to be ordered by count in descending order:

function set_widget_tag_cloud_args($args) {
  $my_args = array('smallest' => 10, 'largest' => 16, 'orderby'=>'count', 'order'=>'DESC' );
  $args = wp_parse_args( $args, $my_args );
return $args;

In the above code, after inserting our parameters into $my_args array, we merge that array with the $args variable. Finally, we return that array.

And we are done.

Note: For the list and explanation of all possible parameters, check the wp_tag_cloud function.

Why the above code needs to merge two arrays is explained next.

When widget_tag_cloud_args filter breaks your tag cloud widget layout

On my first try using widget_tag_cloud_args filter, I simply added parameters I was interested in changing and returned that array as shown here:

function set_widget_tag_cloud_args($args) {
  $args = array('smallest' => 10, 'largest' => 16, 'orderby'=>'count', 'order'=>'DESC' );
return $args;

But the above code broke my styling for tag widget. This is how it looked like:

WordPress broken tag cloud after using widget_tag_cloud_args filter

By examining the generated HTML code, I noticed that the Tag Cloud widget was not showing properly because it was not wrapped with element used by other widgets on the sidebar. Also, the usual <div class="tagcloud"> was missing.

Note: Which wrapping element is used for sidebar widgets is set by register_sidebar function. It can be <li>, <div> or <aside>, depending on the theme.

The reason for this issue is that the default $args parameter of widget_tag_cloud_args filter already contains two elements inside the array:

  • taxonomy (set to current taxonomy)
  • echo (set to false)

If we simply override $args arguments with our own values and we don't include 'echo'=>false, then 'echo'=>true will be used as the default and that causes the tag cloud not to be displayed as a widget, but instead as if the call to wp_tag_cloud function was made, meaning no wrapping with 'before_widget' and 'after_widget' as set by register_sidebar function will occur.

Merging our custom $my_args with $args array using wp_parse_args function solves this problem.

Solution without coding – install a tag cloud plugin

In case when you don’t want to mess with modifying template code or need to drastically change cloud tag widget styles without much of an effort, then adding WordPress plugin might be a better way to go. The Page Tag Cloud plugin is just one such example. For a more concrete list, check the following article. I would only suggest to skip those plugins that were not updated recently.


Editing settings for the tag cloud widget at Dashboard > Appearance > Widgets gives us only basic parameters to modify. For more options, we can use widget_tag_cloud_args filter to change the behavior of the default tag cloud widget. Alternatively, we can just simply add a WordPress plugin that replaces the internal widget.


  1. Simo
    July 23, 2017
    • moped
      April 25, 2019
  2. sj
    March 6, 2019

Write a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.