Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cloud
✓ import cloud from 'd3-cloud';
✗ 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
✓ const layout = d3.layout.cloud();
✗ import { cloud } from 'd3-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.
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
Debug
Known issues
gotchaWords 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.fixTo 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.
affects: >=1.0.0
breakingd3-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.fixFor 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.
affects: >=1.0.0 (when migrating to modern D3/ESM)
gotchaThe 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.fixBe 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).
affects: >=1.0.0
gotchaFor 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.fixUtilize 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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'cloud')
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.
fixFor 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
The `cloud()` function was not invoked to create a layout instance before attempting to call its methods, or the import was incorrect.
fixEnsure 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.
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.
fixIncrease 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.
Audit
Dependencies
d3optionalHistorically, d3-cloud was designed as a D3 layout plugin (d3.layout.cloud). While it can be used independently for layout generation, D3 is commonly used for rendering the output.