npm / d3-cloud
d3-cloud
What changed in d3-cloud 1 to 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-30.
21 breaking1 security7 new APIs and options6 behavior and defaults2 tooling2 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initd3-cloud 235 changes
Breaking changes 19
Invalid arguments now throw instead of being silently replaced, including invalid coordinates, dimensions, padding, random functions, fonts, and canvases.
Both built-in spirals stretch to the aspect ratio only up to 64:1, changing layouts with more extreme aspect ratios.
clear() throws while place() is searching rather than corrupting masks or occupancy.
The event-driven factory API is replaced with the class-based CloudLayout API.
The class-based API introduces CloudSprite in place of the old event-driven factory API.
Custom data is carried by a single datum option, stored by reference on sprites and placed words; other option fields are ignored rather than copied.
The default font size is now 1 instead of sqrt(value); set styling explicitly.
The default rotation is now zero instead of a random multiple of 30 degrees.
The package is ESM-only; the old Browserify and CommonJS distribution shapes are removed.
getSprite() throws if called while a sprite is being drawn to the same canvas.
Input word objects are no longer mutated; placement returns separate plain words and callers control word ordering.
The minimum Node.js version is now 20.
The rectangular strategy visits every point of a 4-pixel grid in aspect-ratio-shaped rings, producing denser packing at any aspect ratio.
Search limits scale with the number of possible placement positions and apply equally to built-in and custom strategies.
size([width, height]) now defines the centered layout box; layouts may grow beyond it.
The old spiral() API is replaced with strategy().
Padding uses round stroke joins, extending exactly padding pixels from glyph outlines instead of up to ten times that at sharp corners.
Text rasters use measured ink bounds, account for overhang and accents, redraw when ink reaches the edge, and use centered text alignment.
The UMD/script-tag build and d3.layout.cloud global are removed; browser scripts must use ESM imports.
Security 1
Placement uses a private copy of each sprite mask and accepts only sprites created by getSprite(), preventing changed or forged sprites from corrupting a layout.
New APIs and options 7
erase() erases a word returned by place().
CloudLayout.getSprite(...) explicitly prepares immutable sprites that have no position and can be placed repeatedly.
Sprites can be extracted from image alpha masks, with optional resizing; images without intrinsic dimensions can be drawn at explicit dimensions.
A built-in noneStrategy provides single-attempt placement.
overflow(true | false) controls whether placement may extend beyond the layout box.
place() lets callers control placement using sprites created by getSprite().
Sparse packed block placement supports effectively unbounded layouts.
Behavior and default changes 4
Image sources may be images, videos, canvases, or ImageBitmaps, including node-canvas, and placed words retain the source type.
Placement tries the seed first, then searches from the nearest possible touch position, skipping positions that cannot fit without collision checks.
Image coordinates mark the sprite center, and text is rendered from x and y with a centered horizontal anchor.
Layouts may share a scratch canvas; a failed draw or readback makes layouts using it request a canvas from their factory again.
Tooling 2
datum is typed generically and inferred from getSprite() options.
The package now includes TypeScript declarations for both the package entry and build/d3-cloud.js.
Fixes and other changes 2
blockSize() throws while place() is searching rather than corrupting masks or occupancy.
Sprite geometry is trimmed to occupied pixels independently of packed row alignment, preventing bounded layouts from rejecting words because of raster slack.
d3-cloud 14 changes
Breaking changes 2
The Bower manifest was removed.
The Tea configuration file was removed.
Behavior and default changes 2
The browser bundle now includes the 1.2.8 change to default rotations, so its rotation behavior is updated.
Default rotation now uses the layout's random() function, making rotations reproducible with a seeded random number generator.