wordcloud2.js

You can install the wordcloud package using npm to include it in your project dependencies.

npm install wordcloud

To create a word cloud, download wordcloud2.js from the src folder, include it in your web page, and call the WordCloud function.

Pass a canvas element (or an HTML element) as the first argument and an options object as the second. The options object must contain a list key, which is an array of arrays where each inner array contains a string (the word) and a number (its weight/size).

Use these options to visualize the grid used for masking:

• drawMask: Set to true to draw squares to mask drawn areas.
• maskColor: Color of the mask squares.
• maskGapWidth: Width of the gaps between mask squares.

To enable interactivity, provide hover and/or click functions in the options object. When these are provided, the library tracks word positions in an internal infoGrid to map mouse events to specific words.

• hover(item, dimension, event): Triggered when the mouse moves over a word. item is the original data item, and dimension contains the bounding box {x, y, w, h}.
• click(item, dimension, event): Triggered when a word is clicked.

Note: Interactivity works on both <canvas> and <div> elements.

Control randomness and user interaction:

Randomness

• shuffle: If true, shuffles points to ensure different results for the same list.
• rotateRatio: Probability of a word rotating (set to 1 to always rotate).

Interaction

• hover: Callback for cursor entry/exit: callback(item, dimension, event).
• click: Callback for word clicks: callback(item, dimension, event).

Control the layout and boundaries of the cloud:

• gridSize: Pixel size of the grid used for marking availability (larger values increase gaps between words).
• origin: The [x, y] origin of the cloud.
• drawOutOfBound: If true, allows words to be drawn partially outside the canvas or larger than the canvas.
• shrinkToFit: If true, shrinks words to fit the canvas (note: this reduces the word's weight).
• shape: The cloud shape. Keywords: 'circle' (default), 'cardioid', 'diamond', 'square', 'triangle-forward', 'triangle' (alias of 'triangle-upright'), 'pentagon', and 'star'. Can also be a polar equation callback.
• ellipticity: Degree of flatness for the shape.

Manage the rendering lifecycle and text orientation:

Timing

• wait: Milliseconds to wait before drawing the next item via setTimeout.
• abortThreshold: If a loop iteration takes longer than this many milliseconds, the rendering aborts.
• abort: Callback function executed when an abort occurs.

Rotation

• minRotation: Minimum rotation in radians.
• maxRotation: Maximum rotation in radians. Set both to the same value for a fixed angle.
• rotationSteps: Forces a specific number of angles (e.g., setting to 2 in a -90°/90° range uses only -90, 0, or 90).

To optimize performance (for example, when a component unmounts in React), you can stop the current rendering process by calling WordCloud.stop().

useEffect(() => {
  ...
  return () => {
    // stop the renderring
    WordCloud.stop();
  };
}, [deps]);

Use the following properties to detect environment capabilities:

• WordCloud.isSupported: Returns false if the browser lacks the necessary functionalities to run the library.
• WordCloud.minFontSize: Returns the value of the browser's minimum font size preference, which may impact canvas rendering.

To render a word cloud, call the WordCloud(elements, options) function.

elements can be a single DOM element (like a <canvas> or a <div>), an array of DOM elements, or a jQuery object.

• If a <canvas> element is provided, the cloud is rendered as an image on the canvas.
• If any other element is provided, the cloud is rendered as a collection of <span> elements (a DOM cloud), which allows for further CSS styling.

options is an object containing configuration settings for the cloud's appearance and behavior.

WordCloud(elements, options);