# FHeatmapChartBuilder

- Human documentation: [https://docs.univer.ai/reference/facade/heatmap-chart-builder](https://docs.univer.ai/reference/facade/heatmap-chart-builder)

- Agent Markdown: [https://docs.univer.ai/reference/facade/heatmap-chart-builder.md](https://docs.univer.ai/reference/facade/heatmap-chart-builder.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/heatmap-chart-builder.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/heatmap-chart-builder.mdx)

---

Fluent, type-specific Builder for Heatmap Charts.

The data source is a matrix-shaped table expressed as one category field plus one or
more numeric value fields. Category values become Y-axis rows, value-field headers
become X-axis columns, and each aligned numeric observation becomes one cell.

## Inheritance

Extends [`FAxisChartBuilder`](https://docs.univer.ai/reference/facade/axis-chart-builder.md). Its inherited members are available on this object.

## Example

Sheet

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Heatmap)
  .setSource({
    range: 'A1:D8',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setCategoryField(0)
  .setValueFields([1, 2, 3])
  .setVisualMapType(univerAPI.Enum.ChartVisualMapType.Continuous)
  .setValueRange(0, 100)
  .setCellLabel({ visible: true, position: univerAPI.Enum.ChartSeriesLabelPosition.Inside })
  .setValueUnit('tickets')
  .build()
await fWorksheet.insertChart(chartInfo)
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const chartInfo = fDocument
  .newChart(univerAPI.Enum.ChartTypeString.Heatmap)
  .setSource([
    ['Day', 'Morning', 'Evening'],
    ['Mon', 24, 62],
    ['Tue', 38, 81],
  ])
  .setCategoryField(0)
  .setValueFields([1, 2])
  .setVisualMapType(univerAPI.Enum.ChartVisualMapType.Continuous)
  .setValueRange(0, 100)
  .setCellLabel({ visible: true, position: univerAPI.Enum.ChartSeriesLabelPosition.Inside })
  .setValueUnit('tickets')
  .build()
await fDocument.insertChart(chartInfo)
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const chartInfo = fSlide
  .newChart(univerAPI.Enum.ChartTypeString.Heatmap)
  .setSource([
    ['Day', 'Morning', 'Evening'],
    ['Mon', 24, 62],
    ['Tue', 38, 81],
  ])
  .setCategoryField(0)
  .setValueFields([1, 2])
  .setVisualMapType(univerAPI.Enum.ChartVisualMapType.Continuous)
  .setValueRange(0, 100)
  .setCellLabel({ visible: true, position: univerAPI.Enum.ChartSeriesLabelPosition.Inside })
  .setValueUnit('tickets')
  .build()
await fSlide.insertChart(chartInfo)
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Heatmap)
  .setSource([
    ['Day', 'Morning', 'Evening'],
    ['Mon', 24, 62],
    ['Tue', 38, 81],
  ])
  .setCategoryField(0)
  .setValueFields([1, 2])
  .setVisualMapType(univerAPI.Enum.ChartVisualMapType.Continuous)
  .setValueRange(0, 100)
  .setCellLabel({ visible: true, position: univerAPI.Enum.ChartSeriesLabelPosition.Inside })
  .setValueUnit('tickets')
  .build()
await fBoard.insertChart(chartInfo)
```

## Setup

Register [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/engine-chart/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/sheets/getting-started/facade.md).

## `@univerjs-pro/engine-chart`

### `FHeatmapChartBuilder.clearCellLabel`

Clears the explicit Heatmap cell-label style. Heatmap cells render without labels until
labels are enabled again with `setCellLabel({ visible: true })`.

```typescript
clearCellLabel(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearCellLabel()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-heatmap-chart-builder.d.ts)

### `FHeatmapChartBuilder.clearValueRange`

Clears the value range configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
clearValueRange(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearValueRange()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-heatmap-chart-builder.d.ts)

### `FHeatmapChartBuilder.clearValueUnit`

Clears the explicit Heatmap value unit.

```typescript
clearValueUnit(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearValueUnit()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-heatmap-chart-builder.d.ts)

### `FHeatmapChartBuilder.resetVisualMapType`

Restores the visual map type to `Continuous` and returns this builder for chaining.

This method executes synchronously.

```typescript
resetVisualMapType(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetVisualMapType()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-heatmap-chart-builder.d.ts)

### `FHeatmapChartBuilder.setCellLabel`

Sets the value label rendered inside each Heatmap cell.

With `{ visible: true }`, omitted style fields default to the cell value, an inside position,
12 px text, the chart font (or Arial), and the active theme's mark-text color.

```typescript
setCellLabel(value: IChartHeatmapLabelSpec): this
```

**Parameters**

* `value` — Required. Cell-label visibility and typography.

**Returns**

This builder for chaining.

**Examples**

```ts
builder
  .setPalette(['#eff6ff', '#1d4ed8'])
  .setValueRange(0, 80)
  .setValueUnit('tickets')
  .setCellLabel({ visible: true, position: univerAPI.Enum.ChartSeriesLabelPosition.Inside })
```

**Types:** [`IChartHeatmapLabelSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/chart-types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-heatmap-chart-builder.d.ts)

### `FHeatmapChartBuilder.setValueRange`

Sets the value range configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setValueRange(min: number, max: number): this
```

**Parameters**

* `min` — Required. The minimum value.
* `max` — Required. The maximum value.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setValueRange(0, 100)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-heatmap-chart-builder.d.ts)

### `FHeatmapChartBuilder.setValueUnit`

Sets the unit appended to the Heatmap visual-map boundary labels.

```typescript
setValueUnit(value: string): this
```

**Parameters**

* `value` — Required. Unit text such as `tickets`.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setValueUnit('tickets')
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-heatmap-chart-builder.d.ts)

### `FHeatmapChartBuilder.setVisualMapType`

Sets the visual map type configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setVisualMapType(value: ChartVisualMapType): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setVisualMapType(univerAPI.Enum.ChartVisualMapType.Continuous)
```

**Types:** [`ChartVisualMapType`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/chart-types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-heatmap-chart-builder.d.ts)