d3-cloud: Word Cloud Layout for JavaScript and Node.js

What d3-cloud Does and Who Needs It

d3-cloud generates word cloud layouts in JavaScript. Given an array of words with associated sizes, it calculates x and y positions, rotations, and font properties so the words can be rendered as a visualization. The project is described in its README as "a Wordle-inspired word cloud layout." It uses HTML5 canvas elements internally for pixel-level collision detection.

The intended users are web developers and data visualization engineers who want to embed word clouds in a browser page or generate them server-side in Node.js. The library handles only the layout computation; rendering the positioned words with SVG or another output format is left to the calling code.

The Sprite Mask Collision Algorithm

The core mechanism is sprite masking on an HTML5 canvas. When positioning each word, d3-cloud renders the word's text onto an offscreen canvas and creates a pixel-level bitmask. It tests the bitmask against the accumulated mask of all previously placed words. If the masks overlap, a collision is detected and the algorithm tries the next position along a spiral.

The spiral starts from the center of the defined rectangular area and steps outward. Two spiral types are available: `archimedean` (the default) and `rectangular`. A custom spiral generator can also be supplied as a function of the form `function(size) { return function(t) { return [x, y]; }; }` where `size` is the `[width, height]` array.

The README states a deliberate limitation: if a word cannot be placed in any position along the spiral, it is not included in the final layout. There is no fallback or warning; words are silently dropped. The README notes this may be addressed in a future release but gives no timeline.

Installing d3-cloud and Running the First Layout

The package is published on npm as `d3-cloud` at version 1.2.9. Install it with:

npm install d3-cloud

The built file is at `build/d3.layout.cloud.js`. This file is referenced in the `main` field of `package.json`, so it loads when you `require` or `import` the package without specifying a path.

To construct a layout, call `d3.layout.cloud()` and chain the configuration methods:

function(d) { return Math.sqrt(d.value); }

This is the default `fontSize` accessor from the README. It maps each word's `value` property to a font size in pixels by taking the square root. You replace it with your own accessor to control sizing.

The layout is asynchronous by default. It uses `setInterval` internally to avoid blocking the browser event loop. When you call `.start()`, placement begins. A `word` event fires each time a word is successfully placed, and an `end` event fires when the algorithm has finished with all words. The `end` listener receives an array of placed word objects and a bounds object with the form `[{x0, y0}, {x1, y1}]`.

For Node.js, the canvas element is not available by default. The README explicitly states you will need to override the default `canvas` generator using the npm `canvas` module.

Configuring Font, Rotation, and Padding

Each configuration method accepts either a constant or a function that receives the word object. The `font` method sets the font face, defaulting to `serif`. The `fontWeight` method defaults to `normal`. The `rotate` method determines how each word is angled; the default accessor is:

() => ~~(random() * 6) - 3) * 30

This produces rotations of -90, -60, -30, 0, 30, 60, or 90 degrees at random. Replacing the accessor with a constant like `0` produces a horizontal-only layout.

The `padding` method sets pixel spacing between words, defaulting to 1. The `random` method accepts a custom random number generator that should return values in `[0, 1)`. Supplying a seeded generator makes layouts reproducible.

The `timeInterval` method caps the time spent per `setInterval` tick. The default is `Infinity`, meaning the algorithm runs in a single tick, which blocks the event loop for large word sets. Setting a smaller value, such as 10 milliseconds, allows the browser to remain responsive during layout.

Limitations and Silent Word Dropping

The placement algorithm's most important constraint is word dropping. When the canvas area is too small for all words, or when many large words compete for the center, some words are simply not included in the result. The `end` event delivers only the words that were placed, not the full input array. There is no separate callback or error for dropped words; calling code must compare input and output to detect them.

The library version is 1.2.9. Development dependencies include browserify for building the standalone bundle. The `build/` directory in the repository contains the pre-built file, so most users do not need to run the build step themselves.

The library has a single runtime dependency: `d3-dispatch` at `^1.0.3`. This is the only piece of D3 it requires; the full D3 bundle is not necessary.

d3-cloud Versus Chart.js WordCloud

The closest npm alternative for word clouds is the Chart.js WordCloud plugin, which integrates with the Chart.js charting library. The difference in approach is architectural: d3-cloud is a standalone layout engine that produces position data and leaves rendering to the consumer, while Chart.js WordCloud is tied to the Chart.js rendering pipeline and requires Chart.js as a peer dependency.

d3-cloud is the appropriate choice when you are already working in a D3-based visualization stack or want precise control over how words are rendered. Chart.js WordCloud is more convenient when you are already using Chart.js and want chart-style configuration with built-in legends and tooltips.

d3-cloud does not produce SVG or HTML directly; it emits position data that your code renders. This makes it more composable but requires more integration work.

Browser and Node.js Usage Patterns

The `examples/` directory in the repository contains two files: `examples/browserify.js` and `examples/node.js`. The node example documents the pattern for overriding the canvas generator with the npm `canvas` module, which is necessary because `document.createElement` is not available in Node.js.

The package's `module` and `jsnext:main` fields both point to `index.js`, the ES module entry point. This means bundlers that respect these fields will import the ES module source directly rather than the pre-built bundle, which enables tree-shaking.

The project is licensed under BSD-3-Clause, which allows use in commercial projects with attribution. The license does not require sharing modifications.

Editorial conclusion

d3-cloud is the right choice for engineers who need a configurable word cloud layout that integrates with D3.js and can run in both browser and Node.js environments. The library's placement algorithm is a known trade-off: words that cannot fit are silently dropped, and the README acknowledges this limitation without a documented fix. Teams that need every word to appear should account for this constraint at the data preparation stage, not in the layout itself. The last push was on 2026-03-09.

Frequently asked questions

Official sources

1. Issues
2. jasondavies/d3-cloud on GitHub
3. License: BSD-3-Clause
4. Project website
5. README