# Visual Map

Control value-based colors, sizes, and the selected range.

Canonical: https://chart.syidax.com/docs/components/visual-map/

<a id="overview"></a>

## sy-visual-map

Connect a continuous color legend or interval filters to a chart.

Choose a dimension supported by the target. This example connects to Heatmap's value.

Base chart tier: Community. Features such as additional renderers and custom branding have separate entitlement requirements.

| Input | Data description |
| --- | --- |
| `for` | The target chart's ID. |
| `dimension` | The data dimension to read. |
| `type` | continuous or piecewise. |
| `min` | Together with max, defines the value range. |

- [Run in Components](https://chart.syidax.com/charts/visual-map) — Change options and view framework-specific code
- [Shared installation and integration](https://chart.syidax.com/docs/getting-started.md)

<a id="example"></a>

## Complete implementation example

```html
<div id="chart-container" style="width: 100%; min-width: 0;"></div>

<script type="module">
  import { defineCustomElement as define0 } from '@syidax/advanced-pro/components/sy-heatmap.js';
  import { defineCustomElement as define1 } from '@syidax/advanced-pro/components/sy-visual-map.js';
  define0();
  define1();

  // Pro: complete registerLicense at app startup using your issued certificate.
  // The website preview certificate is not for use in customer apps.
  const specs = [
    {
      "tag": "sy-heatmap",
      "id": "chart-target",
      "props": {
        "data": [
          {
            "x": 0,
            "y": 0,
            "value": 10
          },
          {
            "x": 1,
            "y": 0,
            "value": 27
          },
          {
            "x": 2,
            "y": 0,
            "value": 44
          },
          {
            "x": 3,
            "y": 0,
            "value": 61
          },
          {
            "x": 4,
            "y": 0,
            "value": 78
          },
          {
            "x": 5,
            "y": 0,
            "value": 95
          },
          {
            "x": 0,
            "y": 1,
            "value": 22
          },
          {
            "x": 1,
            "y": 1,
            "value": 39
          },
          {
            "x": 2,
            "y": 1,
            "value": 56
          },
          {
            "x": 3,
            "y": 1,
            "value": 73
          },
          {
            "x": 4,
            "y": 1,
            "value": 90
          },
          {
            "x": 5,
            "y": 1,
            "value": 17
          },
          {
            "x": 0,
            "y": 2,
            "value": 34
          },
          {
            "x": 1,
            "y": 2,
            "value": 51
          },
          {
            "x": 2,
            "y": 2,
            "value": 68
          },
          {
            "x": 3,
            "y": 2,
            "value": 85
          },
          {
            "x": 4,
            "y": 2,
            "value": 12
          },
          {
            "x": 5,
            "y": 2,
            "value": 29
          },
          {
            "x": 0,
            "y": 3,
            "value": 46
          },
          {
            "x": 1,
            "y": 3,
            "value": 63
          },
          {
            "x": 2,
            "y": 3,
            "value": 80
          },
          {
            "x": 3,
            "y": 3,
            "value": 97
          },
          {
            "x": 4,
            "y": 3,
            "value": 24
          },
          {
            "x": 5,
            "y": 3,
            "value": 41
          },
          {
            "x": 0,
            "y": 4,
            "value": 58
          },
          {
            "x": 1,
            "y": 4,
            "value": 75
          },
          {
            "x": 2,
            "y": 4,
            "value": 92
          },
          {
            "x": 3,
            "y": 4,
            "value": 19
          },
          {
            "x": 4,
            "y": 4,
            "value": 36
          },
          {
            "x": 5,
            "y": 4,
            "value": 53
          }
        ],
        "height": 280,
        "width": 640
      }
    },
    {
      "id": "example-chart",
      "tag": "sy-visual-map",
      "props": {
        "for": "chart-target",
        "type": "continuous",
        "dimension": "value",
        "min": 0,
        "max": 100,
        "calculable": true,
        "color": ["#eee6ff", "#8263d9", "#34265d"],
        "width": 640,
        "height": 64
      }
    }
  ];
  const container = document.querySelector('#chart-container');
  const elements = specs.map(({ tag, id, props }) => {
    const element = document.createElement(tag);
    element.id = id;
    Object.assign(element, props);
    element.setAttribute('aria-label', 'visual-map example chart');
    return element;
  });
  container.replaceChildren(...elements);
  const chart = elements.at(-1);
  const onEvent = event => {
    console.log('rangeChange', event.detail);
  };
  chart.addEventListener('rangeChange', onEvent);
  const observer = new ResizeObserver(([entry]) => {
    const width = Math.max(160, Math.floor(entry.contentRect.width));
    elements.forEach(element => { element.width = width; });
  });
  observer.observe(container);

  // In an SPA, call this function when the view is disposed.
  function disposeChart() {
    observer.disconnect();
    chart.removeEventListener('rangeChange', onEvent);
    container.replaceChildren();
  }
</script>
```

<a id="props"></a>

## Properties

<a id="property-type"></a>

### type

continuous or piecewise.

| Item | Value |
| --- | --- |
| JavaScript property | `type` |
| HTML attribute | `type` |
| Type | `VisualMapType` |
| Default | `'continuous'` |
| Allowed values | `continuous`, `piecewise` |

- [VisualMapType](https://chart.syidax.com/docs/types/VisualMapType.md) — Type definition

<a id="property-min"></a>

### min

Together with max, defines the value range.

| Item | Value |
| --- | --- |
| JavaScript property | `min` |
| HTML attribute | `min` |
| Type | `number` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-max"></a>

### max

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `max` |
| HTML attribute | `max` |
| Type | `number` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-for"></a>

### for

The target chart's ID.

| Item | Value |
| --- | --- |
| JavaScript property | `for` |
| HTML attribute | `for` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-target"></a>

### target

the chart element to colour (the script-set alternative to `for`).

| Item | Value |
| --- | --- |
| JavaScript property | `target` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `VisualMapTargetElement \| null` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [VisualMapTargetElement](https://chart.syidax.com/docs/types/VisualMapTargetElement.md) — Type definition

<a id="property-dimension"></a>

### dimension

The data dimension to read.

| Item | Value |
| --- | --- |
| JavaScript property | `dimension` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `VisualMapDimension` |
| Default | `undefined` |
| Literals in the type | `x`, `y`, `value`, `z`, `index` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [VisualMapDimension](https://chart.syidax.com/docs/types/VisualMapDimension.md) — Type definition

<a id="property-sizeRange"></a>

### sizeRange

visualMap → size: the mark radius (px) at the low / high end of the map (`"4,16"` as an attribute); the legend shows size ticks.

| Item | Value |
| --- | --- |
| JavaScript property | `sizeRange` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `readonly [number, number] \| string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-sizeDimension"></a>

### sizeDimension

the dimension the size reads (default: `dimension`).

| Item | Value |
| --- | --- |
| JavaScript property | `sizeDimension` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `VisualMapDimension` |
| Default | `undefined` |
| Literals in the type | `x`, `y`, `value`, `z`, `index` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [VisualMapDimension](https://chart.syidax.com/docs/types/VisualMapDimension.md) — Type definition

<a id="property-outOfRangeSize"></a>

### outOfRangeSize

the radius of out-of-range values (default: the low end of `sizeRange`).

| Item | Value |
| --- | --- |
| JavaScript property | `outOfRangeSize` |
| HTML attribute | `out-of-range-size` |
| Type | `number` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-pieces"></a>

### pieces

Piecewise: explicit pieces (`[{ min, max, label, color }]` or `[{ value }]`; a JSON string as an attribute). Wins over `categories` / `splitNumber`.

| Item | Value |
| --- | --- |
| JavaScript property | `pieces` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `ReadonlyArray<VisualMapPieceInput> \| string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [VisualMapPieceInput](https://chart.syidax.com/docs/types/VisualMapPieceInput.md) — Type definition

<a id="property-splitNumber"></a>

### splitNumber

Piecewise: equal intervals over `[min, max]` when no pieces / categories are given (default 5).

| Item | Value |
| --- | --- |
| JavaScript property | `splitNumber` |
| HTML attribute | `split-number` |
| Type | `number` |
| Default | `5` |

<a id="property-categories"></a>

### categories

Piecewise: discrete values, one piece each (a comma list as an attribute).

| Item | Value |
| --- | --- |
| JavaScript property | `categories` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `ReadonlyArray<string \| number> \| string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-selectedMode"></a>

### selectedMode

Piecewise: 'multiple' toggles pieces independently, 'single' keeps one piece selected.

| Item | Value |
| --- | --- |
| JavaScript property | `selectedMode` |
| HTML attribute | `selected-mode` |
| Type | `VisualMapSelectedMode` |
| Default | `'multiple'` |
| Allowed values | `multiple`, `single` |

- [VisualMapSelectedMode](https://chart.syidax.com/docs/types/VisualMapSelectedMode.md) — Type definition

<a id="property-selected"></a>

### selected

Piecewise: the initial / controlled selection (`null` = every piece); changing it reports `selectionChanged` with source 'api'.

| Item | Value |
| --- | --- |
| JavaScript property | `selected` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `ReadonlyArray<boolean> \| null` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-itemWidth"></a>

### itemWidth

Piecewise: the swatch size of a piece (ECharts itemWidth / itemHeight).

| Item | Value |
| --- | --- |
| JavaScript property | `itemWidth` |
| HTML attribute | `item-width` |
| Type | `number` |
| Default | `20` |

<a id="property-itemHeight"></a>

### itemHeight

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `itemHeight` |
| HTML attribute | `item-height` |
| Type | `number` |
| Default | `14` |

<a id="property-color"></a>

### color

The ramp: a scheme name (`viridis`, `blues`, `rdbu`, …), a comma list (`#eff6ff,#1d4ed8`), a colour array, or `[t, colour]` stops.

| Item | Value |
| --- | --- |
| JavaScript property | `color` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `VisualMapColorInput` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [VisualMapColorInput](https://chart.syidax.com/docs/types/VisualMapColorInput.md) — Type definition

<a id="property-outOfRangeColor"></a>

### outOfRangeColor

The colour of values outside the selected range (and of non-finite values).

| Item | Value |
| --- | --- |
| JavaScript property | `outOfRangeColor` |
| HTML attribute | `out-of-range-color` |
| Type | `string` |
| Default | `'#d1d5db'` |

<a id="property-orientation"></a>

### orientation

'horizontal' runs min → max left to right, 'vertical' bottom to top.

| Item | Value |
| --- | --- |
| JavaScript property | `orientation` |
| HTML attribute | `orientation` |
| Type | `DataZoomOrientation` |
| Default | `'horizontal'` |
| Allowed values | `vertical`, `horizontal` |

- [DataZoomOrientation](https://chart.syidax.com/docs/types/DataZoomOrientation.md) — Type definition

<a id="property-width"></a>

### width

Chart width in pixels. If the container width changes, update width from a ResizeObserver.

| Item | Value |
| --- | --- |
| JavaScript property | `width` |
| HTML attribute | `width` |
| Type | `number` |
| Default | `320` |

<a id="property-height"></a>

### height

Chart height in pixels. Allow space for axes, titles, and the legend.

| Item | Value |
| --- | --- |
| JavaScript property | `height` |
| HTML attribute | `height` |
| Type | `number` |
| Default | `28` |

<a id="property-calculable"></a>

### calculable

Show the two range handles: the selected range can be dragged, keyed and set from script.

| Item | Value |
| --- | --- |
| JavaScript property | `calculable` |
| HTML attribute | `calculable` |
| Type | `boolean` |
| Default | `false` |

<a id="property-range"></a>

### range

The selected range (`null` / unset = the whole domain); changing it reports `rangeChange` with source 'api'.

| Item | Value |
| --- | --- |
| JavaScript property | `range` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `VisualMapRange \| readonly [number, number] \| null` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [VisualMapRange](https://chart.syidax.com/docs/types/VisualMapRange.md) — Type definition

<a id="property-precision"></a>

### precision

Fixed decimals for the labels (unset = up to two, trimmed).

| Item | Value |
| --- | --- |
| JavaScript property | `precision` |
| HTML attribute | `precision` |
| Type | `number` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-format"></a>

### format

Label formatter (a property — functions cannot be attributes).

| Item | Value |
| --- | --- |
| JavaScript property | `format` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `(value: number) => string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-text"></a>

### text

End captions instead of the numbers: `"High,Low"` (max end first — ECharts `text`).

| Item | Value |
| --- | --- |
| JavaScript property | `text` |
| HTML attribute | `text` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-showLabels"></a>

### showLabels

Show the end labels, and the handle labels while a range is selected.

| Item | Value |
| --- | --- |
| JavaScript property | `showLabels` |
| HTML attribute | `show-labels` |
| Type | `boolean` |
| Default | `true` |

<a id="property-stepFraction"></a>

### stepFraction

Fraction of the selected range one arrow key moves (default 0.1).

| Item | Value |
| --- | --- |
| JavaScript property | `stepFraction` |
| HTML attribute | `step-fraction` |
| Type | `number` |
| Default | `0.1` |

<a id="property-minRangePx"></a>

### minRangePx

The narrowest selectable range, in track pixels (default 8).

| Item | Value |
| --- | --- |
| JavaScript property | `minRangePx` |
| HTML attribute | `min-range-px` |
| Type | `number` |
| Default | `8` |

<a id="property-realtime"></a>

### realtime

Report the frames of a drag (`live: true`); off = only the release reports.

| Item | Value |
| --- | --- |
| JavaScript property | `realtime` |
| HTML attribute | `realtime` |
| Type | `boolean` |
| Default | `true` |

<a id="property-disabled"></a>

### disabled

Set as an HTML attribute or JavaScript property. type: boolean.

| Item | Value |
| --- | --- |
| JavaScript property | `disabled` |
| HTML attribute | `disabled` |
| Type | `boolean` |
| Default | `false` |

<a id="events"></a>

## Events

<a id="event-rangeChange"></a>

### rangeChange

Every range the control shows: a handle drag / key ('control', with `live` frames), `setRange` or the `range` prop ('api').

Event name: `rangeChange`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<VisualMapRangeChangeEventDetail>`.

```javascript
chart.addEventListener('rangeChange', event => {
  console.log(event.detail); // VisualMapRangeChangeEventDetail
});
```

- [VisualMapRangeChangeEventDetail](https://chart.syidax.com/docs/types/VisualMapRangeChangeEventDetail.md) — Type definition

<a id="event-selectionChanged"></a>

### selectionChanged

a piecewise map's selection changed (a piece toggled: 'control'; `setSelected` / the `selected` prop: 'api').

Event name: `selectionChanged`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<VisualMapSelectionChangeEventDetail>`.

```javascript
chart.addEventListener('selectionChanged', event => {
  console.log(event.detail); // VisualMapSelectionChangeEventDetail
});
```

- [VisualMapSelectionChangeEventDetail](https://chart.syidax.com/docs/types/VisualMapSelectionChangeEventDetail.md) — Type definition

<a id="methods"></a>

## Methods

<a id="method-refresh"></a>

### refresh

Re-read the bound chart's extent (while `min` / `max` are unset) and push the binding; the control also does this on the chart's `rendered`.

```typescript
refresh(): Promise<void>
```

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-setRange"></a>

### setRange

Select a range from script (`null` = the whole domain); reports `rangeChange` with source 'api' when it changed.

```typescript
setRange(range: VisualMapRange | readonly [number, number] | null): Promise<VisualMapRange | null>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `range` | `VisualMapRange \| readonly [number, number] \| null` | Required |

Return type: `Promise<VisualMapRange | null>`. Call the method after element registration and await its Promise result.

- [VisualMapRange](https://chart.syidax.com/docs/types/VisualMapRange.md) — Type definition

<a id="method-getRange"></a>

### getRange

The resolved range.

```typescript
getRange(): Promise<VisualMapRange | null>
```

Return type: `Promise<VisualMapRange | null>`. Call the method after element registration and await its Promise result.

- [VisualMapRange](https://chart.syidax.com/docs/types/VisualMapRange.md) — Type definition

<a id="method-setSelected"></a>

### setSelected

piecewise: select pieces from script (`null` = every piece); reports `selectionChanged` with source 'api'.

```typescript
setSelected(selected: ReadonlyArray<boolean> | null): Promise<boolean[] | null>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `selected` | `ReadonlyArray<boolean> \| null` | Required |

Return type: `Promise<boolean[] | null>`. Call the method after element registration and await its Promise result.

<a id="method-getSelected"></a>

### getSelected

piecewise: the per-piece selection (`null` = every piece).

```typescript
getSelected(): Promise<boolean[] | null>
```

Return type: `Promise<boolean[] | null>`. Call the method after element registration and await its Promise result.

<a id="method-togglePiece"></a>

### togglePiece

piecewise: toggle one piece the way a click does (reports source 'api').

```typescript
togglePiece(index: number): Promise<boolean[] | null>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `index` | `number` | Required |

Return type: `Promise<boolean[] | null>`. Call the method after element registration and await its Promise result.

<a id="method-getSpec"></a>

### getSpec

The resolved spec plus the selection: continuous → domain, stops, space, out-of-range colour, calculable, precision + `range`; piecewise → the pieces + `selected`.

```typescript
getSpec(): Promise<VisualMapSnapshot>
```

Return type: `Promise<VisualMapSnapshot>`. Call the method after element registration and await its Promise result.

- [VisualMapSnapshot](https://chart.syidax.com/docs/types/VisualMapSnapshot.md) — Type definition

<a id="method-colorAt"></a>

### colorAt

The colour of a value on this map: the ramp / piece colour inside the selection, `outOfRangeColor` outside it.

```typescript
colorAt(value: number | string): Promise<string>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `value` | `number \| string` | Required |

Return type: `Promise<string>`. Call the method after element registration and await its Promise result.