# Data Zoom

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

Canonical: https://chart.syidax.com/docs/components/data-zoom/

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

## 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.

| Input | Data description |
| --- | --- |
| `for` | The target chart's ID. |
| `showLabels` | Whether to show labels at both ends of the range. |
| `axis` | The target axis to control. |

- [Run in Components](https://chart.syidax.com/charts/data-zoom) — 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/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>
```

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

## Properties

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

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

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

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

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

### orientation

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

| 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-axis"></a>

### axis

The target axis to control.

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

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

- [CartesianAxisId](https://chart.syidax.com/docs/types/CartesianAxisId.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 | `640` |

<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-minRangePx"></a>

### minRangePx

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

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

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

### stepFraction

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

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

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

### showLabels

Whether to show labels at both ends of the range.

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

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

### format

Label formatter (default: up to two decimals).

| 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-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 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
});
```

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

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

## Methods

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

### 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.

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

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

| Arguments | Type | Required |
| --- | --- | --- |
| `window` | `CartesianZoomWindow \| readonly [number, number] \| null` | Required |

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

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

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

### 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.

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

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

### 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.

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