d3-cloud: a canvas word cloud layout for the browser and Node.js
Create word clouds in JavaScript.
At a glance
- What is it?
- d3-cloud is a JavaScript layout that places words with collision testing on HTML5 canvas. It handles the packing, not the rendering, and it silently drops words that do not fit.
- Who is it for?
- Adopt d3-cloud if you need programmatic word placement in a JavaScript build and are willing to supply a canvas and render the output yourself. Do not adopt it if you expect a charting component with axes, legends or a DOM renderer, or if every word must appear.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- jasondavies/d3-cloud3,949 ★ · -2
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| jasondavies/d3-cloud | 4k | 3.9k |
-2 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What d3-cloud actually does, and who it is for
d3-cloud computes positions. It takes an array of word objects, each carrying at least a text string and a value, and returns the same objects with x, y, rotate and size attributes set. It does not draw anything. The README describes it as a Wordle-inspired word cloud layout written in JavaScript that uses HTML5 canvas and sprite masks to reach near-interactive speeds. The rendering step is left to you, whether that means writing to a canvas, emitting SVG, or feeding the coordinates into another library.
That split makes it a fit for developers building a custom visualisation who want the packing problem solved and the presentation left open. It is a poor fit for anyone who wants a finished chart component. There is no DOM output, no colour scale, no tooltip, no legend, and no React or Angular binding in the repository. The examples directory contains two files, browserify.js and node.js, which is roughly the whole surface of documented integration.
Spiral placement and why some words never appear
The start method initialises attributes on the word objects and attempts to place each word, beginning with the largest. Starting from the centre of the rectangular area, each word is tested for collisions against everything already placed. On a collision, the layout moves the word to a new position along a spiral and tests again.
The spiral is configurable. The two built-in options are "archimedean" and "rectangular", and cloud.spiral also accepts a generator function of the form function(size) that returns a function of t producing [x, y]. The default is the archimedean spiral. Placement is incremental because the layout uses setInterval internally to avoid locking the browser event loop; cloud.timeInterval sets the maximum time that can be spent in the current timestep, and it defaults to Infinity.
The consequence of this design is stated plainly in the README: if a word cannot be placed in any of the positions attempted along the spiral, it is not included in the final layout, and the note adds that this may be addressed in a future release. There is no error, no exception and no placeholder. A dense cloud with a small size simply returns fewer words than you passed in. If your visualisation implies that every term is represented, that implication is wrong, and the fix is to read the count from the end event rather than assume it.
Installing d3-cloud and placing a first set of words
The package is published as d3-cloud at version 1.2.9, with main pointing at build/d3.layout.cloud.js and module pointing at index. It depends on d3-dispatch. Install it from npm:
npm install d3-cloudThe README points to the samples in examples/ for usage. The node.js example is the one to read if you are running outside a browser, because the layout needs a canvas to measure text, and the default canvas generator calls document.createElement("canvas"). In Node.js you override it, and the README names the canvas module as the usual choice. The README documents the layout API through accessors such as size, words, padding, rotate, font, fontSize, random and canvas, and the default fontSize accessor is shown as:
function(d) { return Math.sqrt(d.value); }The default rotate accessor is shown as a function producing a multiple of 30 degrees, and the default text accessor as:
function(d) { return d.text; }After start, the end event is dispatched with an array of the word objects that were successfully placed and a bounds object of the form [{x0, y0}, {x1, y1}]. Compare the length of that array with the length of your input array before you draw anything. In the browser, the package build script runs browserify with the standalone name d3.layout.cloud, which is the global the browser build exposes.
The canvas dependency is the real integration cost
Most of the API is accessor plumbing: font, fontStyle, fontWeight, fontSize, rotate, text and padding each accept a constant or a function and return the layout when set. The rotate default is a function that produces a multiple of 30 degrees, which is why clouds built with no configuration come out with words at several angles. Passing a constant of 0 removes the effect entirely.
The awkward part is canvas. The layout draws text into a canvas to build sprite masks for collision testing, so it needs a working canvas implementation wherever it runs. In a browser that is free. On a server it means a native dependency, and the README only says you will almost definitely override the default, naming the canvas module as an example. It does not document the override signature beyond the default function returning a canvas element, and it does not cover font availability in headless environments. If a font is not installed where the process runs, the measured text extents differ from what a browser would produce, and the layout is computed against the wrong boxes. That is a deployment concern the README does not address, and it is the most likely source of a cloud that looks correct locally and wrong in a container.
Determinism is the other practical point. cloud.random sets the internal generator used for initial positions and for the clockwise or counterclockwise direction of the spiral, and it must return a number in [0, 1). The default is Math.random. If you need the same cloud twice, supply your own seeded generator; nothing else in the layout makes placement reproducible.
d3-cloud against drawing words with plain SVG and d3
The obvious alternative is to place text elements yourself in SVG and skip the layout library. With plain d3 you control the coordinate system, the font metrics are the browser's own, and you can animate or restyle individual words with CSS. What you give up is collision handling. Overlapping labels are the normal outcome of random or grid placement, and avoiding them by hand means writing the same spiral search and overlap test that d3-cloud already implements, plus a way to measure each string.
A second alternative is to render the cloud as an image with a general canvas drawing library and accept overlaps. That is cheaper and produces a softer, more decorative result, but it cannot guarantee that a label is readable, which matters when the words carry information rather than atmosphere. d3-cloud sits between those two positions: it does the geometry and leaves the drawing to you. The trade is that you inherit both the canvas measurement step and the responsibility for rendering, and you accept that unplaced words disappear rather than being reported.
Maintenance, licence and what a version bump costs
The repository is not archived and the last push was on 2026-03-09. The package sits at 1.2.9 and the repository has no published releases, so there is no changelog to read for upgrade guidance. The dependency list is one runtime package, d3-dispatch, and one dev dependency, browserify, which keeps the supply chain small. The API is accessor-based and has been stable enough that the README reads as a reference rather than a migration guide.
The licence is BSD-3-Clause, which permits use in closed-source products provided the copyright notice and disclaimer are retained; the LICENSE file is at the repository root. That is a permissive licence, but it is not legal advice and the exact obligations depend on how you redistribute the code, especially if you bundle it into a built asset. The practical upgrade risk is low because the surface is small, but the build step is worth noting: the package main is a browserify bundle, while module points at index, so a modern bundler resolves the source and an older CommonJS require resolves the prebuilt file. If your toolchain changes, check which of the two you are actually loading.
Editorial conclusion
Adopt d3-cloud if you need programmatic word placement in a JavaScript build and are willing to supply a canvas and render the output yourself. Do not adopt it if you expect a charting component with axes, legends or a DOM renderer, or if every word must appear. Before committing, check how many words your data loses at your chosen size by listening to the end event, and confirm the canvas override works in your Node version.
Frequently asked questions
Does d3-cloud render the word cloud itself?
No. It computes x, y, rotate and size on the word objects and dispatches an end event with the placed words and their bounds. Drawing the result is left to your own canvas or SVG code.
Why are some words missing from my d3-cloud output?
The README states that a word which cannot be placed in any position attempted along the spiral is not included in the final layout. There is no error raised, so compare the placed array from the end event against your input array.
Can d3-cloud run in Node.js?
Yes, but the default canvas generator calls document.createElement("canvas"), so the README says you will almost definitely override it when using Node.js, naming the canvas module as an example.
How do I install d3-cloud?
Install the d3-cloud package from npm. The package main points at build/d3.layout.cloud.js and the module field points at index, and the README directs you to the samples in examples/ for usage.
Can I make the layout reproducible?
Set your own generator with cloud.random. It is used for the initial position of each word and for the spiral direction, and it must return a number in the range [0, 1); the default is Math.random.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/jasondavies-d3-cloud)Star history chart for your README
[](https://hysenlabs.com/projects/jasondavies-d3-cloud)Was this useful?