How to use WP-Cumulus shortcodes

Contrary to what I originally thought when I released WP-Cumulus, it seems most people prefer to use it on their blog’s sidebar. I estimate that at least 80% of users use the widget. But the plugin still has two other ways to embed the movie into your blog, and version 1.20 greatly improves the most important of those. Shortcodes can be incredibly useful, and version 1.20 of my plugin now properly supports them.


WordPress 2.5 introduced an API that allows us plugin creators to easily create square bracket ‘tags’ that users can type into blog posts and pages to trigger plugin output. WP-Cumulus has used something similar since day one, but the official shortcodes API allows for a lot more flexibility.

The most important change is that you can pass parameters. For Cumulus, this means you can override your default settings each time you embed a tag cloud into a post. Lets assume you’ve set up the non-widget version of the tag cloud to be 500 pixels wide. You can now use the following shortcode to display it at 300 pixels.

[wp-cumulus width="300"]

If you’d instead like a cloud with red tags and a transparent background, here’s the code for that:

[wp-cumulus tcolor="ff0000" tcolor2="ff0000" trans="true"]

Supported attributes

Here is a complete list of the attributes WP-Cumulus currently supports:

AttributeUsed forPossible valuesExample
widthWidth of the tag cloudNumber of pixels (positive integer)width=”300″
heightHeight of the tag cloudNumber of pixels (positive integer)height=”240″
tcolorTag colorHEX color value without the ‘#’ prefixtcolor=”ffcc00″
tcolor2Tag color for less important tagsHEX color value without the ‘#’ prefixtcolor2=”cc9900″
hicolorTag highlight colorHEX color value without the ‘#’ prefixhicolor=”ffffff”
bgcolorTag cloud background colorHEX color value without the ‘#’ prefixbgcolor=”333333″
speedRotation speedPrecentage, higher means fasterspeed=”150″
transBackground transparency“true” or “false”trans=”true”
distrEven tag distributions along sphere“true” or “false”distr=”true”
argsArgments to be passed to the ‘wp_tag_cloud’ function (experimental, use at own risk)URL encoded stringargs=”smallest=10″
modeTag/Category mode“tags”, “cats” or “both”mode=”tags”

Default values

By using any of these attributes, you override the values entered under ‘Settings->WP Cumulus”. These serve as the defaults used when using the shortcode, so simply entering [wp-cumulus] into a post will result in a tag cloud with those settings. If you have only one cloud inside a post or page it’s probably best to change the main settings. The attributes listed above will allow you to have multiple clouds inside posts, all with different settings.

WordPress 2.5 and up

Please note that since the shortcodes API was introduced in WordPress 2.5, none of this will work on older versions. The new lowercase shortcodes replace the old [WP-CUMULUS] one. That still works for now, but is ‘deprecated’ for blogs running WP 2.5 or newer.


  1. WP-Cumulus v1.20 is still missing the “ı” and “İ” Turkish caracters…

    Comment by Izzy — March 12, 2009 @ 8:04 am

  2. Hi Izzy. Thanks for pointing that out. As it turns out I forgot to update the appropriate file. Major oops. I’m uploading the right one right now, so if you download the plugin again it should work.

    Comment by Roy — March 12, 2009 @ 10:12 am

  3. Hi Roy and thanks for your plugin. I just upgraded and now it’s not working. You can see it in my site. I even tried reactivating, reloading, resetting and all res, with no result. I would appreciate some help.

    Comment by Ximena Eduarda — March 12, 2009 @ 4:17 pm

    • @Ximena: Looks like it’s working OK now? You might want to change the highlight color to something other than black though to make it stand out more.

      Comment by Roy — March 13, 2009 @ 1:42 pm

  4. Thanks! Your plugin is very very special! So, please, I would like change font type. It`s possible? tnx 4 hlp.

    Comment by WMK — March 12, 2009 @ 9:07 pm

    • Hi WMK. Yes you can change the font. Details are here.

      Comment by Roy — March 13, 2009 @ 1:44 pm

  5. Thanks for this very nice plug-in !

    Comment by luc legay — March 12, 2009 @ 10:06 pm

  6. Nice. This would make for and awsome organizational chart when one wants to show the interconnection of multiple groups. Is it possible to use this function with expandable boxes containing editable text? I am not a web designer, nor do I play one on TV. Just curious and stumbled upon this from the “Raw Milk” blog site. m-

    Comment by Michael — March 13, 2009 @ 4:14 am

  7. Hi

    Is it possible to use this plugin outside of WordPress e.g. in a Vb.Net .Net 2 Web App?

    Comment by Ian — March 13, 2009 @ 3:40 pm

  8. Hi found the link for that will have a look…

    Comment by Ian — March 13, 2009 @ 4:04 pm

  9. Link: WP-Cumulus: Una sfera in flash per le Tags | .:[ Byte Zone ]:.
  10. Not available for blogger??? 🙁 I just love these gadgets

    Comment by mina — March 15, 2009 @ 4:01 pm

    • @mina: Amanda keeps a Blogger port over at

      Comment by Roy — March 16, 2009 @ 1:26 pm

  11. Hi! Is a very very nice plugin. But I think there’s a problem when you are selecting text outside the movie (the movie still rotate).


    Comment by Guglie — March 16, 2009 @ 9:44 pm

  12. hi! i love this widget. Can this be used for non-wordpress site? or do you have any plug-ins that i can apply for social networking sites like

    Comment by leah — March 18, 2009 @ 1:10 pm

  13. This is a cool plugin. Someone forward me this NY Times link which has a similar cloud. Is this a customized version of your code? If not, could your code be hacked to do this, point to a podcast or video or audio file?

    Thank you for a great plugin.

    Comment by Jim — March 18, 2009 @ 1:57 pm

  14. Hi Jim. That is a great page. I’d seen something similar before, and it’s definitely far more ambitious than my little tag cloud 🙂

    I’m pretty sure WP-Cumulus could serve as a basis from something like this, but since you’d be displaying radically different content, the 3D code would probably be the only thing left once you’d be done.

    Comment by Roy — March 18, 2009 @ 2:08 pm

  15. Maybe using the wp_list_categories parameters could somehow be used. I’ll have to ponder and maybe get a chance to experiment. And I just saw your flickr/picasa widget. Very cool!

    Comment by Jim — March 18, 2009 @ 2:47 pm

  16. can this be used in blogger site ?

    Comment by mei — March 19, 2009 @ 6:40 am

  17. @mei: Amanda over at maintains a Blogger version called Blogumus.

    Comment by Roy — March 19, 2009 @ 9:10 am

  18. got it. thanks Roy!

    Comment by leah — March 21, 2009 @ 8:00 am

  19. Dear, such a beatuful post, i loved it, still am trying to understand how to make it workable on my site. I just installed the plugin and thats it. can u please make a video tutorial of this plugin in
    it will be very helpful. and if u made, please let me know as soon as possibe.
    thanks alooooooot

    Comment by Naqqash — March 21, 2009 @ 10:27 pm

  20. Hi Roy just getting back to thank you, I did not see your answer on the 13th., yes it is working now and tks for the advice

    Comment by Ximena Eduarda — March 21, 2009 @ 11:47 pm

  21. Hi Roy,

    thanks for this great widget.
    How can I make the widget stay in backround if an image gets opened? On my blog the widget stays in front of the picture. Is there a fix?

    Comment by bs_de — March 23, 2009 @ 12:29 pm

    • Hi bs_de. You should try enabling the transparent background option. If that does not help there could be a great number of things happening. It depends on how your blog was built.

      Comment by Roy — March 23, 2009 @ 1:43 pm

  22. That’s it! Thank you very much!

    Comment by bs_de — March 23, 2009 @ 4:34 pm

  23. how can i download it?

    Comment by Kabitirtha koley — March 25, 2009 @ 5:38 am

  24. @Kabitirtha: It’s available from

    Comment by Roy — March 25, 2009 @ 9:47 am

  25. Is it possible to install to a WP blog located on

    Comment by Oscar — March 26, 2009 @ 1:53 pm

  26. Hi Oscar. I don’t think allows you to install plugins at all, do they? So I guess you’d have to convince them to add WP-Cumulus to the entire system…

    Comment by Roy — March 26, 2009 @ 3:24 pm

  27. Link: WP Cumulus 1.20 русская версия - 3D облако меток | RaZoR Blog
  28. Hello, i´d like to show tags for public and for private articles on my blog. Is this possible?

    Comment by marcel — March 27, 2009 @ 2:57 pm

    • @Marcel: I don’t use private posts on my blog, but if wp_tag_cloud can display the tags for them, so can WP-Cumulus.

      Comment by Roy — March 27, 2009 @ 8:53 pm

  29. Link: Продвинутое анимированное облако тегов WP-Cumulus | | Проблемы и решения в Web-дизайне
  30. Thanks for this very nice plug-in & share it with us 😀

    Comment by ery — March 31, 2009 @ 8:35 pm

  31. Hi,
    Is there a way to feed into it flickr tags? IE NOT the flickr pics, but the tags from flickr pics/galleries etc?


    Comment by Stewart Gilray — March 31, 2009 @ 11:08 pm

    • @Stewart: I’m not sure Flickr even publishes those tags as a feed. If it does, it should be possible to modify Cumulus to display them, but it will require some extensive changes.

      Comment by Roy — April 1, 2009 @ 9:00 am

  32. @Roy, thanks anyway, I am aware of a WP plugin (out dated now) that does pull the TAGS down from an account, so just wondered if you’d already done something similar. Thanks anyway.

    Comment by Stewart Gilray — April 1, 2009 @ 12:34 pm

  33. Hi Roy,
    The temptation to create a website came to me after seeing the tag cloud on a wordpress blog of a friend’s. I wanted to try to do something different.
    I created my main page as a tag cloud (instead of the traditional welcome page with menu).
    It works well for Mozilla firefox, but when I use IE (not just in my PC but at any internet cafe as well), I get this message :

    The XML page cannot be displayed
    Cannot view XML input using style sheet. Please correct the error and then click the Refresh button, or try again later.


    Parameter entity must be defined before it is used. Error processing resource ‘…

    Is there any solution in form of code set tweaks i can make to solve this??


    Comment by Kaavya — April 2, 2009 @ 8:50 am

  34. Hi Kaavya. I have to be honest with you, I can make heads not tails of the header in your site. It looks like XSL to me, which I haven’t done in ages. Perhaps you should try (X)HTML instead?

    Comment by Roy — April 2, 2009 @ 9:19 am

  35. Hi Roy. I instal Wp Cumulus on my joomla 1.5 but i can’t change the world’s insade.I like the worlds to be same of my article on my page but that’s is defolt automatic i don’t know …..a try everyting…pls help me man.

    Comment by Dzoc — April 2, 2009 @ 6:56 pm

    • @Dzoc: You should contact the author of the Joomla port. I’m afraid I know nothing about the inner workings of Joomla.

      Comment by Roy — April 2, 2009 @ 9:12 pm

  36. Hi roy ,thanks for this really cool site. i download WP-Cumulus (it’s wonderful) for joomla version, but i need it for Persian language ( it’s like Arabic language with 4 more words) (right to left)… can you help me how i can use it in this language?? is there any way???

    Comment by Mehdi — April 5, 2009 @ 1:51 pm

  37. Hi Roy,

    This is a great plug-in indeed. Very fascinating and eye catching. However, I face a little trouble to change the font face. Any trick to do it?


    Comment by Eric — April 5, 2009 @ 5:54 pm

  38. hello

    i strived to insert a tag cloud in my blogSpot / Blog blog. but I am not fully satisfied. I would like a Cumulus.

    is it possible or not to insert one in a Blogger blog ?

    if no, is there alternative so that i can have an animated cloud with mty tags, like the WP-Cumulus.



    Comment by OochyKoochy — April 7, 2009 @ 1:43 am

    • @OochyKoochy: Yes you can. Amanda over at Bloggerbuster has written a Blogger version.

      Comment by Roy — April 7, 2009 @ 9:01 am

  39. Quite frustrated with tag cloud. I have pored over the files in my theme and in the tagcloud plugin folder. Although the number 550 appears nowhwere, as I have replaced it everywhere, the tagcloud swf ONLY appears at 550 px. No matter what settings I change, this is the ONLY width. Very annoying.

    Comment by Caleb — April 7, 2009 @ 3:54 am

    • @Caleb: You shouldn’t need to edit any files. There are two sets of settings (one for the widget, another for the shortcode version) that you can use to adjust the dimensions etc. One is located under ‘settings->wp cumulus’, the other is ‘inside’ the widget at ‘appearance->widgets’

      Comment by Roy — April 7, 2009 @ 8:59 am

  40. Thanks Roy. Indeed I altered those settings first. I only went to the files themselves when that didn’t work. When I view the source of the page it very clearly is still set to 550 width. It must, I can only assume, be a problem with the theme.

    Comment by Caleb — April 7, 2009 @ 3:57 pm

    • @Caleb: Please contact me by email. I’m sure it’s going to turn out to be easy to fix.

      Comment by Roy — April 8, 2009 @ 10:21 am

  41. Thanks a lot for everything Roy. There was a problem in the .swf object link , in the xhtml document of the index page.

    With a litte help from a flash expert friend of mine, I was able to solve it.
    Everyone loved the used of the tag cloud on my webpage.


    Comment by Kaavya — April 8, 2009 @ 7:42 am

  42. Link: Плагин для WordPress Wp-cumulus. | Lady Maksima
  43. @ Roy

    well, i did so… does not work. i followed instructions in full. inserted as indicated, where indicated…

    hummm. me think: i’m scpetic. if you have any instance of a blogger / blogspot blog on which it works and that i can look, i may be able to ask the blog owner tips on how to insert the code and how they fixed the whole thing up.



    Comment by OochyKoochy — April 11, 2009 @ 5:31 pm

  44. Dear Roy,

    Thanks for this nice plugin, I use it with Arabic language but when I click on arabic link I moved to empty destination without the arabic text for example:

    if the link go to /tags/مرحبا it is move me to /tags/ only and it strip the arabic text

    please note that when I view the html source I find the correct url.

    Please advice.


    Comment by Mjarwan — April 20, 2009 @ 11:24 am

  45. how do i use this on (username) blogs?

    Comment by olrayt — April 21, 2009 @ 2:09 pm

  46. oh just read the other comment re: with cumulus. please delete my previous post 😀

    Comment by olrayt — April 21, 2009 @ 2:10 pm

  47. hi Roy,
    Quite frustrated with tag cloud. I try to install it on my site, but it dosn’t works.
    Markup errors seems ok. Deactivated a lot of plugs.
    I can see only see the title from the widget and a with field in my sidbar.
    I like so much this plug. maybe you can give me some hints.



    Comment by Manni — April 25, 2009 @ 7:32 pm

  48. Hi Manni. When I right-click the flash in your sidebar, I get a “movie not loaded” error. This means the movie can’t be loaded from . When I go to that url I’m redirected too your blog’s front page, so there might be something wrong with your htaccess rules, or some other redirection mechanism. Please look into this. I’m pretty sure that will fix your issue.

    Comment by Roy — April 25, 2009 @ 7:58 pm

  49. Hi Roy,

    ok thanks for the hint.



    Comment by Manni — April 25, 2009 @ 8:22 pm

  50. In my page I have links, that passed to flash, like this:

    But when I clicked in flash at this tag I go to

    This is wrong page. Even with encoding (whis is not necessary) this link should be:

    Comment by Theo — April 28, 2009 @ 12:34 am