Overview

wordCloud is a specialized tool for generating word cloud visualizations. Word clouds are a visual representation that intuitively displays the frequency of keywords in text data through words of different sizes, colors, and positions to reflect the importance or weight of words.

When using the wordCloud component, users can easily transform text data into visual word clouds. It supports highly customizable configuration options, including word size ranges, color mapping, rotation angles, and layout algorithms, thereby meeting diverse visualization needs. Additionally, wordCloud can seamlessly integrate with other G2 features, such as data filtering, interactive event binding, etc., further enhancing user experience.

Whether used to display trending topics on social media, analyze user comment sentiment, or present keyword distribution, wordCloud can elegantly help users quickly gain insights into trends and patterns behind the data. wordCloud is not only simple to use but also delivers excellent performance, making it an ideal choice in the field of data visualization.

Getting Started

import { Chart } from '@antv/g2';

const chart = new Chart({
  container: 'container',
});

chart.options({
  type: 'wordCloud', // Specify chart type as word cloud
  data: {
    type: 'fetch',
    value: 'https://assets.antv.antgroup.com/g2/philosophy-word.json',
  },
  layout: {
    spiral: 'rectangular', // Word cloud layout mode: rectangular spiral layout
  },
  encode: { color: 'text' }, // Map data field `text` to word cloud color
  legend: false,
  axis: false,
  tooltip: false,
});

chart.render();

For more examples, please visit the Chart Examples - Text page.

Configuration

encode

Configure visual channels for wordCloud mark, an important configuration that defines the mapping relationship between data fields and visual properties, determining how data is transformed into visual representation.

For more encode configurations, please visit the encode introduction page.

scale

scale is used to define how data maps to visual properties (such as color, size, shape, etc.). In the context of cell usage, the common role of scale is to provide mapping rules for each visual channel (such as color, size, position, etc.), enabling data points to be accurately represented.

For more scale configurations, please visit the scale introduction page.

padding

Configure margins of wordCloud container, you can configure margins in different directions through padding{Position}

type Position = 'Top' | 'Bottom' | 'left' | 'right';

Comparison with padding configuration in layout

Property	Description	Type	Example
option.padding	Configure margin of wordCloud container	number
option.layout.padding	Set spacing between words in pixels, can be a specific value or dynamic function	number | (word: any) => number

layout

spiral

spiral is a parameter that controls the word cloud layout algorithm, determining how words are arranged on the canvas and their path patterns. By adjusting spiral, you can optimize the visual effect, layout density, and performance of the word cloud.

(() => {
  const spiralMap = [
    {
      label: 'Archimedean Spiral',
      spiral: 'archimedean',
    },
    {
      label: 'Rectangular Spiral',
      spiral: 'rectangular',
    },
  ];

  const chart = new G2.Chart();

  chart.options({
    type: 'wordCloud',
    data: {
      type: 'fetch',
      value: 'https://assets.antv.antgroup.com/g2/philosophy-word.json',
    },
    layout: {
      spiral: 'rectangular',
    },
    encode: { color: 'text' },
  });

  const handleSetSpiral = (spiral) => {
    // Set selected coordinate system
    chart.options({
      layout: { spiral },
    });
    chart.render(); // Re-render chart
  };

  // layout-spiral selector
  const selectorContainer = document.createElement('div');
  selectorContainer.textContent = 'Choose spiral ';
  const selector = document.createElement('select');
  selector.innerHTML = spiralMap.map(
    (spiral, index) =>
      `<option value="${spiral.spiral}" ${index === 0 ? 'selected' : ''}>${
        spiral.label
      }</option>`,
  );
  selector.onchange = (e) => {
    handleSetSpiral(e.target.value);
  };
  selectorContainer.appendChild(selector);
  const node = chart.getContainer();
  node.insertBefore(selectorContainer, node.childNodes[0]);

  chart.render();

  return node;
})();

imageMask

imageMask is a key configuration item for controlling word cloud shape. Its function is to limit the word cloud layout within the contour range of a specified image mask, thereby generating word cloud effects that match the image shape.

imageMask receives a mask image, and the WordCloud layout algorithm analyzes the pixel information of the imageMask image, treating non-transparent areas of the image as areas where words can be placed, while transparent areas prohibit word placement. Words dynamically adjust their size and position within non-transparent areas based on weight (such as word frequency).

Notes:

• Image quality: Mask images should typically be monochrome (black and white) images. Generally, word clouds define shapes based on non-white areas.
• Image loading: When using image masks, ensure that image resources are fully loaded, otherwise rendering issues may occur.
• Performance impact: Complex shapes (such as high-resolution images) may affect word cloud construction speed.

import { Chart } from '@antv/g2';

const chart = new Chart({
  container: 'container',
});

chart.options({
  type: 'wordCloud',
  layout: {
    imageMask:
      'https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*LKU4TYEiB-4AAAAAAAAAAAAADmJ7AQ/original',
    fontSize: 12,
  },
  data: {
    type: 'fetch',
    value:
      'https://gw.alipayobjects.com/os/antvdemo/assets/data/antv-keywords.json',
  },
  encode: { color: 'name', text: 'name' },
  legend: false,
});

chart.render();

style

Composite graphic marks need to distinguish graphic configurations through different prefixes.

type FontStyle = 'normal' | 'italic' | 'oblique';

type FontWeight = 'normal' | 'bold' | 'lighter';

type TextAlign = 'left' | 'center' | 'right';

type TextBaseline = 'top' | 'middle' | 'bottom';

Try it out: