Density Map.

PRO

Show concentrations of observations as a smooth density surface.

<sy-density-map>Installation and integration API reference

LIVE EXAMPLE

Density

Match the page theme

Interact with the chart to see selection and range-change results here.

Estimate density around observed points. All values are sample data.

View code

Current preview

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

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

  // Pro: complete registerLicense at app startup using your issued certificate.
  // The website preview certificate is not for use in customer apps.
  const specs = [
    {
      "id": "example-chart",
      "tag": "sy-density-map",
      "props": {
        "data": [
          {
            "x": 0,
            "y": 7,
            "weight": 1
          },
          {
            "x": 16,
            "y": 4,
            "weight": 2
          },
          {
            "x": 29,
            "y": -3,
            "weight": 3
          },
          {
            "x": 37,
            "y": -7,
            "weight": 1
          },
          {
            "x": 44,
            "y": -5,
            "weight": 2
          },
          {
            "x": 55,
            "y": 2,
            "weight": 3
          },
          {
            "x": -1,
            "y": 17,
            "weight": 1
          },
          {
            "x": 15,
            "y": 15,
            "weight": 2
          },
          {
            "x": 29,
            "y": 9,
            "weight": 3
          },
          {
            "x": 38,
            "y": 4,
            "weight": 1
          },
          {
            "x": 45,
            "y": 4,
            "weight": 2
          },
          {
            "x": 55,
            "y": 10,
            "weight": 3
          },
          {
            "x": -3,
            "y": 26,
            "weight": 1
          },
          {
            "x": 14,
            "y": 26,
            "weight": 2
          },
          {
            "x": 29,
            "y": 21,
            "weight": 3
          },
          {
            "x": 39,
            "y": 15,
            "weight": 1
          },
          {
            "x": 47,
            "y": 13,
            "weight": 2
          },
          {
            "x": 55,
            "y": 18,
            "weight": 3
          },
          {
            "x": -4,
            "y": 35,
            "weight": 1
          },
          {
            "x": 13,
            "y": 37,
            "weight": 2
          },
          {
            "x": 29,
            "y": 33,
            "weight": 3
          },
          {
            "x": 40,
            "y": 26,
            "weight": 1
          },
          {
            "x": 48,
            "y": 23,
            "weight": 2
          },
          {
            "x": 56,
            "y": 26,
            "weight": 3
          },
          {
            "x": -5,
            "y": 43,
            "weight": 1
          },
          {
            "x": 11,
            "y": 47,
            "weight": 2
          },
          {
            "x": 28,
            "y": 45,
            "weight": 3
          },
          {
            "x": 41,
            "y": 38,
            "weight": 1
          },
          {
            "x": 49,
            "y": 33,
            "weight": 2
          },
          {
            "x": 57,
            "y": 35,
            "weight": 3
          },
          {
            "x": -5,
            "y": 51,
            "weight": 1
          },
          {
            "x": 10,
            "y": 56,
            "weight": 2
          },
          {
            "x": 27,
            "y": 56,
            "weight": 3
          },
          {
            "x": 41,
            "y": 50,
            "weight": 1
          },
          {
            "x": 51,
            "y": 44,
            "weight": 2
          },
          {
            "x": 58,
            "y": 44,
            "weight": 3
          }
        ],
        "kernel": "gaussian",
        "bandwidth": 9,
        "columns": 60,
        "rows": 40,
        "width": 640,
        "height": 360,
        "brandPosition": "bottom-right",
        "brandLogo": ""
      }
    }
  ];
  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', 'density-map example chart');
    return element;
  });
  container.replaceChildren(...elements);
  const chart = elements.at(-1);
  const onEvent = event => {
    console.log('pointClick', event.detail);
  };
  chart.addEventListener('pointClick', 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('pointClick', onEvent);
    container.replaceChildren();
  }
</script>

Usage and data

Explore clusters and spatial concentration among many points.

Density is an estimate, not a raw observation. Results depend on bandwidth and coordinate units.

Data contract

Property	Input format
`data`	An array of { x, y, weight? }.
`bandwidth`	The range over which the kernel is applied.
`kernel`	The kernel used for density estimation.

Updating data

Assign a new array or object to the property instead of mutating values inside an array. Chart events provide selection results through event.detail. When disposing of the view, clean up ResizeObserver and event listeners registered by your app.

Add to your interface

The code tabs below the preview contain the full data, options, event bindings, and responsive sizing for the current example. Copy them into an app project, such as Vite, that can resolve the installed packages.

Shared sy-chart API versus direct tags

API reference

The full public API for sy-density-map. Pass objects and arrays as JavaScript properties. Select a name to view usage code and type definitions.

Key properties

Attribute / Property	Type / Default	Description
	`DensityMapInput`Default: undefined	An array of { x, y, weight? }.
	`number`Default: 640	Chart width in pixels. Update with ResizeObserver when the container changes.
	`number`Default: 400	Chart height in pixels.
brandLogo	`string`Default: undefined	The default is the Syidax logo. With the Pro chart.branding entitlement, use none or a PNG, JPEG, or WebP data URL.
brandPosition	`'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`Default: 'bottom-right'	The corner where the logo is anchored. Applies equally to Community and Pro, on screen and in image exports.
cellSize	`number`Default: 3	CSS px per estimate cell (the grid follows the plot size); `columns` / `rows` override it.
	`DensityMapBandwidthInput`Default: 'auto'	The range over which the kernel is applied.
bandwidthUnit	`DensityMapBandwidthUnit`Default: 'data'	`data` (default) — the bandwidth is in data units; `px` — in CSS px of the plot.
	`DensityMapKernel`Default: 'gaussian'	The kernel used for density estimation.
	`number`Default: 0.02	Cells under this fraction of the peak density are empty (the background shows through).
	`number`Default: 0.06	Set as an HTML attribute or JavaScript property. type: number.
densityUnit	`DensityMapUnitInput`Default: 'mass'	Allowed values: mass, per-area. Default: 'mass'.
xAxis	`XAxisInput`Default: undefined	One x axis, or `[bottom, top, …]` slots (the multi x-axis; a slot may carry its own `min` / `max`, `kind: 'log' \| 'time'` or `linkedTo` per the shared contract).
yAxis	`YAxisInput`Default: undefined	One y axis, or `[left, right, …]` — a later slot may carry its own `min` / `max` (a second unit for the same y), a `kind` or `linkedTo`.
gridLines	`CartesianGridLinesInput`Default: undefined	Grid lines default OFF (the plane tiles the plot).
	`CartesianCrosshairInput`Default: undefined	Crosshair that follows the cursor across the plot.
	`CartesianZoomInput`Default: undefined	Settings for zooming and the visible range.
chartTitle	`string`Default: undefined	The title inside the chart. Explain the data's unit and meaning alongside it.
chartSubtitle	`string`Default: undefined	The subtitle inside the chart.
	`CartesianTooltipInput`Default: undefined	Tooltip settings for pointer-driven values, position, and content.
tooltipEnabled	`boolean`Default: true	Set as an HTML attribute or JavaScript property. type: boolean.
animated	`boolean`Default: false	Whether to animate initial display and data changes.
animationDuration	`number`Default: 600	Animation duration in milliseconds.
animationEasing	`DensityMapEasing`Default: 'ease-out'	Allowed values: linear, ease-out, ease-in, ease-in-out. Default: 'ease-out'.
animationType	`DensityMapAnimationType`Default: undefined	Allowed values: initial, update. Default: undefined.

Other properties 21

Attribute / Property	Type / Default	Description
xMin	`number`Default: undefined	Explicit domain ends (an omitted end follows the point extent padded by `padding`; `x-axis` / `y-axis` `min` / `max` also set them).
xMax	`number`Default: undefined	Set as an HTML attribute or JavaScript property. type: number.
yMin	`number`Default: undefined	Set as an HTML attribute or JavaScript property. type: number.
yMax	`number`Default: undefined	Set as an HTML attribute or JavaScript property. type: number.
	`number`Default: 0.05	The fraction of the span padded on each automatic domain end.
	`number`Default: undefined	Set as an HTML attribute or JavaScript property. type: number.
	`number`Default: undefined	Set as an HTML attribute or JavaScript property. type: number.
computePath	`DensityMapComputePathInput`Default: 'auto'	Allowed values: auto, cpu, gpu. Default: 'auto'.
	`string \| ReadonlyArray<string> \| ReadonlyArray<readonly [number, string]>`Default: undefined	The colour ramp over the density domain (a scheme name, a colour list / comma list, or `[t, colour]` stops).
valueMin	`number`Default: undefined	Density domain ends; an omitted end follows 0 … the peak.
valueMax	`number`Default: undefined	Set as an HTML attribute or JavaScript property. type: number.
emptyColor	`string`Default: 'transparent'	The colour of an empty (under-threshold) cell — transparent by default.
	`DensityMapLodMode`Default: 'smooth'	The plane's level of detail: `smooth` (bilinear between cell centres — the default here), `auto`, `point`, `area`.
enableMouseTracking	`boolean`Default: true	Set as an HTML attribute or JavaScript property. type: boolean.
tooltipFormat	`(detail: DensityMapPointEventDetail) => string`Default: undefined	Pass as a JavaScript property. type: (detail: DensityMapPointEventDetail) => string.
streamSource	`DensityMapStreamSource`Default: undefined	A stream source for live data. Check the contract for the specific type.
streamMax	`number`Default: undefined	The maximum number of streaming data points to retain.
streamWindow	`number`Default: undefined	The streaming data range to keep visible.
visualMap	`VisualMapBinding \| null`Default: undefined	A visual-map binding (a `sy-visual-map` snapshot + dimension); it overrides `colors` / `value-min` / `value-max` while bound.
	`DensityMapEngineMode`Default: 'auto'	Renderer selection: auto, standard, or pro. Engine selection is separate from permission to use a Pro chart type.
	`DensityMapUnavailableBehaviour`Default: 'fallback'	`fallback` shows the on-chart notice when the renderer cannot run; `error` throws.

Events 14

Events	Detail type	Description
	`DensityMapRenderResult & { tier: DensityMapEngineTier; engine?: ChartEngineStatus }`	Emits rendering results in detail when chart drawing completes.
	`DensityMapPointEventDetail`	A point selection event. Read the selected data and index from CustomEvent.detail.
	`DensityMapPointEventDetail \| null`	CustomEvent.detail type: DensityMapPointEventDetail \| null. Event names are case-sensitive.
	`CartesianCrosshairEventDetail \| null`	CustomEvent.detail type: CartesianCrosshairEventDetail \| null. Event names are case-sensitive.
	`ChartPointContextMenuEventDetail<DensityMapPointEventDetail>`	CustomEvent.detail type: ChartPointContextMenuEventDetail<DensityMapPointEventDetail>. Event names are case-sensitive.
	`{ count: number }`	CustomEvent.detail type: { count: number }. Event names are case-sensitive.
	`{ dropped: number }`	CustomEvent.detail type: { dropped: number }. Event names are case-sensitive.
	`void`	CustomEvent.detail type: void. Event names are case-sensitive.
	`void`	CustomEvent.detail type: void. Event names are case-sensitive.
	`void`	CustomEvent.detail type: void. Event names are case-sensitive.
	`CartesianTooltipEventDetail`	Whether to display the built-in tooltip.
	`void`	CustomEvent.detail type: void. Event names are case-sensitive.
	`CartesianTooltipActionEventDetail`	CustomEvent.detail type: CartesianTooltipActionEventDetail. Event names are case-sensitive.
	`CartesianZoomChangeEventDetail`	Fired after every zoom change (drag / pan / wheel / pinch / keyboard / api / reset) with the new state.

Methods 39

Stencil methods return Promises. Use await within an async function to read the result.

Method / Arguments	Return type	Description
	`Promise<ChartDataTable>`	Current normalized table, including the retained stream; independent of GPU availability.
	`Promise<DensityMapRenderResult>`	Draws a frame now; rejects with the SyidaxLicenseError while the type is not entitled or the chart is frozen.
	`Promise<DensityMapEngineTier>`	An asynchronous method. Check the argument and return types below.
	`Promise<string \| undefined>`	The reason the renderer cannot run (`undefined` while it runs).
data: DensityMapInput	`Promise<void>`	An asynchronous method. Check the argument and return types below.
point: DensityMapPoint \| DensityMapTuple	`Promise<void>`	An asynchronous method. Check the argument and return types below.
points: ReadonlyArray<DensityMapPoint \| DensityMapTuple>	`Promise<void>`	An asynchronous method. Check the argument and return types below.
count: number	`Promise<void>`	An asynchronous method. Check the argument and return types below.
points: ReadonlyArray<DensityMapPoint \| DensityMapTuple>	`Promise<void>`	An asynchronous method. Check the argument and return types below.
	`Promise<DensityMapStreamSource \| undefined>`	An asynchronous method. Check the argument and return types below.
options: { duration?: number; easing?: DensityMapEasing; enabled?: boolean; type?: DensityMapAnimationType }	`Promise<void>`	An asynchronous method. Check the argument and return types below.
	`Promise<void>`	An asynchronous method. Check the argument and return types below.
	`Promise<void>`	An asynchronous method. Check the argument and return types below.
	`Promise<void>`	An asynchronous method. Check the argument and return types below.
cssX: number, cssY: number	`Promise<DensityMapPointEventDetail \| null>`	The estimate cell under host-relative CSS coordinates, or null (the density waits for a pending readback).
col: number, row: number	`Promise<number \| null>`	The density of a cell in the public unit (`null` under the threshold or outside the grid).
x: number, y: number	`Promise<number \| null>`	The density at a data-space point in the public unit (`null` outside the domain or under the threshold).
	`Promise<DensityMapValueExtent \| null>`	The density extent of the estimate in the public unit (min 0, max = the peak, finite = cells over the threshold).
col: number, row: number	`Promise<CartesianTooltipEventDetail \| null>`	An asynchronous method. Check the argument and return types below.
index: number	`Promise<CartesianTooltipEventDetail \| null>`	An asynchronous method. Check the argument and return types below.
	`Promise<void>`	An asynchronous method. Check the argument and return types below.
col: number, row: number	`Promise<DensityMapPointEventDetail \| null>`	An asynchronous method. Check the argument and return types below.
	`Promise<{ columns: number; rows: number; cells: number }>`	An asynchronous method. Check the argument and return types below.
	`Promise<DensityMapDomain>`	The data domain the grid spans.
	`Promise<DensityMapBandwidth>`	The resolved bandwidth (data units, CSS px, cells; `auto` when Silverman chose it).
	`Promise<{ kernel: DensityMapKernel; x: number[]; y: number[]; radius: { x: number; y: number } }>`	An asynchronous method. Check the argument and return types below.
	`Promise<DensityMapComputeStats>`	The statistics of the last estimate (points, grid, kernel, bandwidth, radius, compute time, peak, mass).
	`Promise<Float32Array>`	An asynchronous method. Check the argument and return types below.
	`Promise<{ values: Float32Array; densityMax: number; mass: number; binned: number; finite: number; computeMs: number; radius: { x: number; y: number } }>`	An asynchronous method. Check the argument and return types below.
binding: VisualMapBinding \| null	`Promise<VisualMapBinding \| null>`	Bind (or clear with null) a visual-map snapshot; it wins over the `visualMap` prop until the prop changes again.
	`Promise<VisualMapBinding \| null>`	An asynchronous method. Check the argument and return types below.
request?: VisualMapExtentRequest	`Promise<VisualMapExtent \| null>`	The extent of a dimension: `value` = the density (0 … peak), `x` / `y` = the domain, `index` = the cell indexes.
request: CartesianZoomRequest	`Promise<CartesianZoomChangeEventDetail \| null>`	Zoom to explicit windows in data units: `x` / `y` as `{ min, max }` or `[min, max]` (`null` clears that orientation); `xAxis` / `yAxis` name the axis by id or slot index (default: the primary axis).
factor: number, anchorFraction?: number	`Promise<CartesianZoomChangeEventDetail \| null>`	Scale the current windows by `factor` (< 1 zooms in) around `anchorFraction` (0..1, default centre).
delta: { x?: number; y?: number }	`Promise<CartesianZoomChangeEventDetail \| null>`	Slide the zoomed windows by data units (`{ x?, y? }`); a no-op at the full extent.
	`Promise<CartesianZoomChangeEventDetail \| null>`	Back to the full extent.
	`Promise<CartesianZoomState \| null>`	The current zoom state (`null` = full extent).
request?: CartesianZoomExtentRequest	`Promise<CartesianZoomExtentDetail \| null>`	The full extent (and key) of the primary — or the named — master axes (the field's x / y domain).
	`Promise<ChartEngineStatus>`	Requested engine vs what runs, and why (CHART-ADD-08): the decision for the current inputs, read without side effects (ProChartLicense.engineStatus); a renderer that failed at run time reports engine-unsupported.

Density Map.

Density

Usage and data

Data contract

Updating data

Feature examples

Wide density radiusPRO

Epanechnikov kernelPRO

Inspect values with the pointerPRO

Crosshair trackingPRO

Drag to zoom and panPRO

Replay animationPRO

AnimationPRO

AxisPRO

BandwidthPRO

ComputePRO

CrosshairPRO

Data inputPRO

KernelPRO

Large datasetsPRO

RenderPRO

SizePRO

TooltipPRO

Visual mapPRO

Zoom and panPRO

Context menuPRO

Data context menuPRO

Read coordinates and dataPRO

OverviewPRO

Streaming · Add and update live dataPRO

Add to your interface

API reference

Key properties