Repository navigation
v0.4.0 — framework-agnostic monorepo: core + Svelte, React, Vue, Angular, Solid, Next
The release that took openTagCloud from a Svelte 5 component to a
framework-agnostic tag cloud with seven packages — and the first version
published to npm as a monorepo.
Upgrading from 0.2.x/0.3.x? The Svelte component keeps its package name
(opentagcloud) and its API. Two things moved — see the⚠️ Breaking
changes section at the end.
📦 One engine, seven packages
All layout logic lives in @opentagcloud/core — zero dependencies, plain
TypeScript. Every adapter is a thin (~60–100 line) wrapper that renders tags in
its own framework's template syntax, so SSR and hydration stay native, then
hands the container to the shared engine.
| Package | Use with |
|---|---|
@opentagcloud/core |
Vanilla JS, script tag, <otc-tag-cloud>, custom adapters |
opentagcloud |
Svelte 5 / SvelteKit (name unchanged) |
@opentagcloud/react |
React 18+ — ships 'use client', works in Next.js |
@opentagcloud/vue |
Vue 3 / Nuxt |
@opentagcloud/angular |
Angular 17+ — standalone component |
@opentagcloud/solid |
SolidJS / SolidStart |
@opentagcloud/next |
Next.js (alias of the React adapter) |
The core splits cleanly in two: prepareTags() is pure and DOM-free (safe
during SSR, and the reason every adapter produces identical markup), while
TagCloudLayout is the packer, driven entirely by data-fs / data-weight /
data-key attributes — it doesn't care which framework rendered the elements.
🚫 No build step required
@opentagcloud/core also ships a browser global that registers a light-DOM
<otc-tag-cloud> custom element, so a cloud can be one tag on any page:
<script src="https://unpkg.com/opentagcloud/dist/opentagcloud.vanilla.js"></script>
<otc-tag-cloud style="height: 320px" min-px="14" max-px="44"
items='[{"label":"JavaScript","weight":95},{"label":"Rust","weight":60}]'>
</otc-tag-cloud>Items work as a JSON attribute or an items property; mount() and
defineElement() are also importable from opentagcloud/vanilla.
✨ Layout features
- Fit to container — with an externally imposed height, the packer scales
the font ramp to fill the box instead of packing to natural area. Auto-height
containers keep area-based packing, so layout can never feed back on itself.
(Scaled both ways here; 0.4.1
makes it grow-only.) - Movement animations — re-packs FLIP smoothly from old positions, new tags
scale in, via--otc-move-transition. Honorsprefers-reduced-motion; the
initial pack never animates. - Incremental stability (opt-in
incremental) — unchanged tags keep their
positions across item updates, so live-updating clouds stay calm. - RTL support — tags position with
inset-inline-start, so the whole layout
mirrors underdir="rtl". estimateCloudHeight()— pure, DOM-free height estimate for reserving
min-heightduring SSR to reduce layout shift.- Accessibility —
ariaLabelannounces each tag's weight to screen readers,
minOpacitylets themes hold WCAG AA contrast, and transitions respect
reduced-motion. - Performance — collision detection via a spatial hash and incremental
farthest-point anchor ordering; a 400-tag re-pack runs in ~15 ms. - Text fidelity — labels are never rewritten. Hyphenated words render inside
white-space: nowrapspans, so copy/paste, find-in-page and screen readers
see the real string.
✅ Tests
61 unit tests and 18 Playwright end-to-end tests, all in CI: core unit tests
(including golden RNG values that guard SSR/hydration scatter parity), render
tests for all five framework adapters, and browser tests asserting no
overlaps, deterministic layout, the loop-safety invariant, RTL mirroring, fit
mode, and the UMD/custom-element path.
🌐 Live examples
hkoren.github.io/openTagCloud —
interactive examples plus standalone pages for the vanilla/custom-element,
RTL, and Svelte demos, deployed from main.
⚠️ Breaking changes
- CSS class names are now
.otc-tag/.otc-cloud(they must be global,
unscoped classes). Custom styling that targeted.tag/.cloudneeds
updating. dist/is no longer committed, sonpm install github:hkoren/openTagCloud
is replaced by the npm packages above.- The Svelte component's own props and behavior are unchanged.
Install
npm install opentagcloud # Svelte 5 + vanilla mount() + <otc-tag-cloud>
npm install @opentagcloud/react # or /vue, /angular, /solid, /next, /core