sy-data-zoom

Data Zoom

Change a target chart's visible range with a slider.

sy-data-zoom

Let users select a region of interest within a wide data range.

This is not a standalone data chart. Place it in the same document as the target and set for to the target's unique ID.

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

InputData description
forThe target chart's ID.
showLabelsWhether to show labels at both ends of the range.
axisThe target axis to control.

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/components/sy-line-chart.js';
  import { defineCustomElement as define1 } from '@syidax/advanced/components/sy-data-zoom.js';
  define0();
  define1();

  const specs = [
    {
      "tag": "sy-line-chart",
      "id": "chart-target",
      "props": {
        "engine": "standard",
        "series": [
          {
            "name": "Organic",
            "color": "#8263d9",
            "values": [24, 29, 27, 38, 43, 40, 52, 58, 53, 68, 76, 84]
          },
          {
            "name": "Direct",
            "color": "#239c91",
            "values": [15, 19, 17, 24, 22, 29, 32, 30, 39, 42, 40, 51]
          },
          {
            "name": "Referral",
            "color": "#e99954",
            "values": [8, 11, 9, 15, 13, 19, 17, 23, 22, 28, 25, 33]
          }
        ],
        "xAxis": {
          "kind": "category",
          "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
        },
        "yAxis": {
          "kind": "linear",
          "min": 0
        },
        "zoom": {
          "enabled": true
        },
        "height": 280,
        "width": 640
      }
    },
    {
      "id": "example-chart",
      "tag": "sy-data-zoom",
      "props": {
        "for": "chart-target",
        "showLabels": true,
        "width": 640,
        "height": 36
      }
    }
  ];
  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', 'data-zoom 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

for

The target chart's ID.

ItemValue
JavaScript propertyfor
HTML attributefor
Typestring
Defaultundefined

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 drive (the script-set alternative to for).

ItemValue
JavaScript propertytarget
HTML attributePass objects, arrays, and callbacks as JavaScript properties
TypeDataZoomTargetElement | null
Defaultundefined

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

orientation

'horizontal' drives the x window, 'vertical' the y window.

ItemValue
JavaScript propertyorientation
HTML attributeorientation
TypeDataZoomOrientation
Default'horizontal'
Allowed valuesvertical, horizontal

axis

The target axis to control.

ItemValue
JavaScript propertyaxis
HTML attributePass objects, arrays, and callbacks as JavaScript properties
TypeCartesianAxisId
Defaultundefined

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

width

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

ItemValue
JavaScript propertywidth
HTML attributewidth
Typenumber
Default640

height

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

ItemValue
JavaScript propertyheight
HTML attributeheight
Typenumber
Default28

minRangePx

The narrowest window, in track pixels (default 8).

ItemValue
JavaScript propertyminRangePx
HTML attributemin-range-px
Typenumber
Default8

stepFraction

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

ItemValue
JavaScript propertystepFraction
HTML attributestep-fraction
Typenumber
Default0.1

showLabels

Whether to show labels at both ends of the range.

ItemValue
JavaScript propertyshowLabels
HTML attributeshow-labels
Typeboolean
Defaulttrue

format

Label formatter (default: up to two decimals).

ItemValue
JavaScript propertyformat
HTML attributePass objects, arrays, and callbacks as JavaScript properties
Type(value: number) => string
Defaultundefined

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

disabled

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

ItemValue
JavaScript propertydisabled
HTML attributedisabled
Typeboolean
Defaultfalse

Events

rangeChange

Every window the slider shows: gestures / keys ('slider'), the chart moving on its own ('chart'), setWindow ('api').

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

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

Methods

refresh

Re-read the target's extent and window (the slider also does this on the target's rendered and zoomChange).

typescript
refresh(): Promise<void>

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

setWindow

Set the window from script (null = the full extent); the chart follows with zoomChange.source = 'api'.

typescript
setWindow(window: CartesianZoomWindow | readonly [number, number] | null): Promise<CartesianZoomWindow | null>
ArgumentsTypeRequired
windowCartesianZoomWindow | readonly [number, number] | nullRequired

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

getWindow

An asynchronous method. Check the argument and return types below.

typescript
getWindow(): Promise<CartesianZoomWindow | null>

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

getExtent

An asynchronous method. Check the argument and return types below.

typescript
getExtent(): Promise<ZoomExtent | null>

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