D3 Word Cloud Layout

Common errors

• TypeError: Cannot read properties of undefined (reading 'cloud')

  cause The d3-cloud library was not imported or initialized correctly, or the global 'd3' object (for legacy usage) was not available when d3-cloud was loaded.
  fix For modern usage, ensure you are using `import cloud from 'd3-cloud';` and then `cloud()`. For legacy D3 integration, ensure the `d3` library is loaded globally before `d3-cloud`'s script.

• TypeError: layout.start is not a function

  cause The `cloud()` function was not invoked to create a layout instance before attempting to call its methods, or the import was incorrect.
  fix Ensure you create an instance of the layout: `const layout = cloud();` (for modern ESM) or `const layout = d3.layout.cloud();` (for legacy global D3).

• Some words are not appearing in the final word cloud, even if space seems available.

  cause The d3-cloud algorithm attempts to place words along a spiral. If a word cannot find an uncollided position within its search, it is discarded.
  fix Increase the `size` of the layout, decrease `padding`, adjust the `fontSize` accessor to make words smaller (e.g., `d => Math.sqrt(d.value) * 5` instead of `* 10`), or reduce the total number of words in the input array. Check the output of the 'end' event to identify which words were dropped.

Warnings

• gotcha Words that cannot be placed within the specified layout size (due to collisions or insufficient space) are silently omitted from the final output array. Users expecting all input words to always appear might be surprised.
  Fix: To ensure all words are placed, consider increasing the layout size, reducing font sizes, decreasing padding, or implementing a custom collision detection strategy. Monitor the 'end' event output to see which words were successfully placed.
• breaking d3-cloud was originally designed for older D3 versions (v3-v4) and could extend the global `d3` object (e.g., `d3.layout.cloud()`). Modern D3 (v5+) and module bundlers require importing `d3-cloud` as a standalone module.
  Fix: For modern JavaScript and TypeScript projects, always use `import cloud from 'd3-cloud';` and instantiate the layout directly with `cloud()`. Avoid relying on global `d3` object extension.
• gotcha The library outputs word position data for rendering on an HTML5 Canvas, not directly for SVG. While the data can be adapted for SVG, the intrinsic sprite mask optimization is specific to canvas.
  Fix: Be prepared to implement rendering logic using Canvas API contexts or convert the output data for SVG element creation (e.g., using D3 for SVG rendering).
• gotcha For very large word lists or complex layouts, the layout algorithm can be computationally intensive and might block the browser's event loop, leading to UI freezes. The `timeInterval` method can help mitigate this.
  Fix: Utilize the `.timeInterval(milliseconds)` method to yield control back to the browser periodically, allowing the UI to remain responsive. Adjust the `milliseconds` value based on performance needs.

Install

• npm install d3-cloud npm
• yarn add d3-cloud yarn
• pnpm add d3-cloud pnpm

Imports

• cloud
  wrong:

  import { cloud } from 'd3-cloud';

  correct:

  import cloud from 'd3-cloud';

  d3-cloud exports its layout function as the default export for modern ESM usage.
• cloud

  const cloud = require('d3-cloud');

  For CommonJS environments, the module is imported directly to get the default layout function.
• d3.layout.cloud
  wrong:

  import { cloud } from 'd3-cloud';

  correct:

  const layout = d3.layout.cloud();

  This is the legacy usage pattern for older D3 versions (v3-v4) where d3-cloud would extend the global d3 object. Requires D3 to be loaded globally before d3-cloud. For modern D3, use the default ESM import.

Quickstart

This quickstart demonstrates how to configure and run the d3-cloud layout, setting dimensions, words, font properties, and handling the 'end' event to retrieve the placed words.

import cloud from 'd3-cloud';

interface Word {
  text: string;
  value: number;
  size?: number;
  x?: number;
  y?: number;
  rotate?: number;
  font?: string;
  style?: string;
  weight?: string;
}

const wordsData: Word[] = [
  { text: "TypeScript", value: 60 },
  { text: "JavaScript", value: 50 },
  { text: "D3", value: 45 },
  { text: "Cloud", value: 40 },
  { text: "Canvas", value: 35 },
  { text: "Layout", value: 30 },
  { text: "Example", value: 25 },
  { text: "Development", value: 20 },
  { text: "Web", value: 15 },
  { text: "Visualization", value: 55 }
];

const width = 960;
const height = 500;

// Create a new cloud layout instance
const layout = cloud<Word>()
  .size([width, height])
  .words(wordsData)
  .padding(5)
  .rotate(() => Math.floor(Math.random() * 5) * 30 - 60) // Rotate words by -60, -30, 0, 30, 60 degrees
  .font("Impact")
  .fontSize(d => Math.sqrt(d.value) * 8) // Scale font size based on word value
  .on("end", (words: Word[], bounds: [{ x0: number, y0: number }, { x1: number, y1: number }]) => {
    console.log("Word cloud layout generation complete.");
    console.log("Successfully placed words:", words.map(w => ({ text: w.text, size: w.size, x: w.x, y: w.y, rotate: w.rotate })));
    console.log("Overall cloud bounds:", bounds);
    // In a real application, you would typically render these 'words' to an HTML5 Canvas or SVG element.
  });

layout.start(); // Start the layout algorithm