Overview

jQCloud is a jQuery plugin that builds neat and pure HTML + CSS word clouds and tag clouds that are actually shaped like a cloud (otherwise, why would we call them 'word clouds'?).

Forked from Luca Ongaro

Installation

Bower

The plugin is available on Bower. Add jqcloud2 to your bower.json file or install it manually with bower install jqcloud2.

Includes

Include the Javascript file in your page after jQuery and optionally the CSS file (see Colors & sizes section).

<script src="bower_components/jqcloud2/dist/jqcloud.min.js"></script>

<link rel="stylesheet" href="bower_components/jqcloud2/dist/jqcloud.min.css">
AngularJS

Using AngularJS?

An Angular directive is also available.

Usage

Apply the plugin to a container (preferably a <div>) and provide at least a list of words (see Words options section).

$('#keywords').jQCloud(words);

Container dimensions & position

The cloud container must have defined dimensions, either via CSS or via th width and height options.

Additionally the container must have a defined position (other than static), if you don't define one your self, the plugin will overwrite the position to relative.

Words options

Each item in the words array must be an object with the following attributes.

Name type default description
text string required Text of the word
weight number required Defines the relative importance of the word. The range is arbitrary and will be linearly mapped to a discrete scale from 1 to steps
html object {} An object of custom attributes which will be added to the word, such as class, title or data-myvar. the id will be overrided by jQCloud with an internal value.
handlers object {} List of event handlers which will be attached to the <span> containing the word with jQuery .on() method.
afterWordRender function null Function called after the word is rendered. this refers to the jQuery object for the <span> containing the word

Cloud options

You can provide an object of options has second parameter.

$('#keywords').jQCloud(words, {
  width: 500,
  height: 350
});
Name type default description
width integer Fixed width of the container, will default to container current width
height integer Fixed height of the container, will default to container current height
center object {x: 0.5, y:0.5} Position of the center of the cloud relatively to the container
autoResize boolean false If the container has dynamic dimensions, set this option to true to update the cloud when the window is resized.
steps integer 10 Number of "steps" to map the words on, depending on their weight (see Colors & sizes section)
classPattern string 'w{n}' Pattern used to generate the CSS class added to each word. {n} is replaced by the weight of the word (from 1 to steps)
afterCloudRender function null Function called after the whole cloud is fully rendered. this is the container jQuery object
delay integer 0 or 10 Number of milliseconds to wait between each word draw. Defaults to 10 if there are 50 words or more to avoid browser freezing during rendering. Can also be used for neat display animation!
shape string 'elliptic' Cloud shape, elliptic' or 'rectangular'
removeOverflowing boolean true Don't render words which would overflow the container
encodeURI boolean true Encode special characters in words link
colors array | function [] Colors used instead of CSS declaration (see Colors & sizes section), can be:
  • An array of colors from most to less important
  • A function taking a step number as only parameter and returning a valid CSS color
fontSize array | object | function [] Text sizes used instead of CSS declaration (see Colors & sizes section), can be:
  • An array of sizes (px, em or %) from most to less important
  • An object with from and to values, expressed in fraction of container width (eg: 0.1, 0.04)
  • A function taking the container width, the container height and a step number as parameters and returning a valid CSS font size

Colors & sizes

There are two ways to customize the cloud look and feel: pure CSS or JS configuration.

CSS customization

The plugin will add to each word of the cloud a CSS class based on classPattern. There will be steps classes. With the default configuration these classes are w10, w9, w8, w7, w6, w5, w4, w3, w2, w1.

The included CSS file jqcloud.css is intended as an example and a base on which you can develop your own style.

JS customization

Alternatively you can totally get rid of the CSS configuration and use the colors and fontSize parameters to directly inform the plugin which style to apply to the words.

Nice colors!

Hint: use TinyGradient library to generate nice gradients.

Methods

update

Use the update method to dynamically change the list of words in the cloud.

$('#keywords').jQCloud('update', new_words);

destroy

Completely destroy the cloud and it's data.

$('#keywords').jQCloud('destroy');