WordCloudFlat

WordCloudFlat renders all words on a single layer with smooth zoom (Ctrl + Wheel or pinch) and pan. Ideal when depth navigation is not needed.

Must be a descendant of WordCloud.

Heavy demo

Cache demo (useCache)

The layout algorithm runs once per unique dataset and configuration. Pass useCache to persist the result to localStorage — subsequent page loads render instantly without re-running the algorithm.

Props

Prop	Type	Default	Description
fontUrl	string	—	Required. URL of the font file (TTF/OTF/WOFF). Must be self-hosted. Place the file in your project’s public/ directory and pass the path (e.g. '/fonts/MyFont.ttf'). Note: WOFF2 is not supported; use TTF, OTF, or WOFF.
maxZoom	number	2.0	Maximum zoom level (minimum is always 1).
layout	WordCloudFlatLayout	{}	Layout and sizing options (see below).
a11y	WordCloudFlatA11y	{}	Accessibility labels and ARIA text (see below).
onWordClick	(word: WordItem) => void	—	Called when a word is clicked.
useCache	string | symbol | true	—	Persist the computed layout to localStorage. true derives a key from a hash of the data and layout params (recommended for single-cloud pages). Pass a string or symbol to set an explicit key — useful when multiple clouds share the same page. The stored entry is automatically invalidated when data or layout params change. Call clearCache() on the component instance to clear it manually.

layout

Key	Type	Default	Description
fontSizeContrast	number	2.0	Power-curve exponent. Higher = top words dominate more; lower = more uniform sizes.
topWordArea	number	0.5	Fraction of viewport area targeted by the largest word.
randomness	number	0.5	Randomness applied to word placement. 0 = grid-like, 1 = maximum scatter.

a11y

Key	Type	Default	Description
zoomValueText	(zoom: number) => string	(z) => `${z.toFixed(1)}x`	aria-valuetext for the built-in zoom slider. Use for localisation.
zoomLabel	string	'Zoom'	Accessible label text for the zoom slider.
panHint	string	'Arrow keys to pan'	Short visible hint shown inside the keyboard pan control when focused.
panLabel	string	'Pan view. Use arrow keys to move.'	Screen-reader description for the keyboard pan control button.
resetPanLabel	string	'Reset pan (double-click)'	Screen-reader label for the reset pan button.
fullscreenLabel	string	'Enter fullscreen'	Screen-reader label for the enter-fullscreen button.
exitFullscreenLabel	string	'Exit fullscreen'	Screen-reader label for the exit-fullscreen button.

Usage

<script lang="ts">
  import { WordCloud, WordCloudFlat, WordCloudLabel } from '@shamokit/svelte-wordcloud';
  import type { WordItem } from '@shamokit/svelte-wordcloud';

  // Place your font file in public/fonts/ and reference it by path.
  // External CDN URLs are blocked in production; self-hosting is required.
  const FONT_URL = '/fonts/NotoSansJP.ttf';

  const words: WordItem<{ link?: string }>[] = [
    { word: 'Svelte',     counts: 120, link: 'https://svelte.dev' },
    { word: 'TypeScript', counts: 95,  link: 'https://www.typescriptlang.org' },
    { word: 'Vite',       counts: 80,  link: 'https://vitejs.dev' },
    { word: 'Three.js',   counts: 70,  link: 'https://threejs.org' },
    { word: 'WebGL',      counts: 60 },
    { word: 'Threlte',    counts: 55,  link: 'https://threlte.xyz' },
    // add more words...
  ];

  function handleWordClick(word: WordItem<{ link?: string }>) {
    if (word.link) window.open(word.link, '_blank');
  }
</script>

<WordCloud data={words} --wc-background="#0d1a0d" --wc-color="#a8e6a3">
  <WordCloudLabel>
    {#snippet label({ props })}
      <span {...props} style="position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)">
        Technology word cloud
      </span>
    {/snippet}
  </WordCloudLabel>

  <WordCloudFlat fontUrl={FONT_URL} onWordClick={handleWordClick} useCache={true} />
</WordCloud>

clearCache() example

<script lang="ts">
  import { WordCloud, WordCloudFlat } from '@shamokit/svelte-wordcloud';

  let cloudRef = $state<{ clearCache(): void } | null>(null);
</script>

<WordCloud data={words}>
  <WordCloudFlat fontUrl={FONT_URL} useCache="my-cloud" bind:this={cloudRef} />
</WordCloud>

<button onclick={() => cloudRef?.clearCache()}>Clear cache</button>