sy-visual-map

Visual Map

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

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
Change options and view framework-specific code
Shared installation and integration

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>

Properties

type

continuous or piecewise.

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

VisualMapType
Type definition

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.

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.

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.

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
Type definition

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
Type definition

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.

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
Type definition

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.

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
Type definition

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`

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

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
Type definition

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.

itemWidth

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

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

itemHeight

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

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

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
Type definition

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'`

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
Type definition

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`

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`

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`

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
Type definition

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.

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.

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.

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`

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`

minRangePx

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

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

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`

disabled

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

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

Events

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
Type definition

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
Type definition

Methods

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.

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
Type definition

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
Type definition

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.

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.

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.

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
Type definition

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.