# Dumbbell

Connect two measurements to show their difference.

Canonical: https://chart.syidax.com/docs/components/dumbbell/

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

## sy-dumbbell-chart

Compare two reference points per category, such as before and after or target and actual.

Explain the meaning and unit of both endpoints. The connecting length represents their difference.

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

| Input | Data description |
| --- | --- |
| `data` | An array of { category, values: [low, high] }. |
| `color` | Set endpoint colors as [first, second]. |
| `groups` | Names for the two endpoints. |

- [Run in Components](https://chart.syidax.com/charts/dumbbell) — 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-dumbbell-chart.js';
  define0();

  const specs = [
    {
      "id": "example-chart",
      "tag": "sy-dumbbell-chart",
      "props": {
        "engine": "standard",
        "data": [
          {
            "category": "Team A",
            "values": [35, 65]
          },
          {
            "category": "Team B",
            "values": [50, 75]
          },
          {
            "category": "Team C",
            "values": [42, 82]
          }
        ],
        "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', 'dumbbell 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>
```

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

## Properties

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

### data

An array of { category, values: [low, high] }.

| Item | Value |
| --- | --- |
| JavaScript property | `data` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `ReadonlyArray<DumbbellDatum>` |
| Default | `[]` |

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

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

### categories

Optional category-label override. When set, replaces the per-datum `category` labels.

| Item | Value |
| --- | --- |
| JavaScript property | `categories` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `ReadonlyArray<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-groups"></a>

### groups

Names for the two endpoints.

| Item | Value |
| --- | --- |
| JavaScript property | `groups` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `ReadonlyArray<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-lowName"></a>

### lowName

Compatibility alias for `groups[0]`.

| Item | Value |
| --- | --- |
| JavaScript property | `lowName` |
| HTML attribute | `low-name` |
| 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-highName"></a>

### highName

Compatibility alias for `groups[1]`.

| Item | Value |
| --- | --- |
| JavaScript property | `highName` |
| HTML attribute | `high-name` |
| 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-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 | `360` |

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

### brandLogo

The default is the Syidax symbol and wordmark. With the Pro chart.branding entitlement, set none to remove it or provide a PNG, JPEG, or WebP data URL to replace it.

| Item | Value |
| --- | --- |
| JavaScript property | `brandLogo` |
| HTML attribute | `brand-logo` |
| 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-brandPosition"></a>

### brandPosition

The corner where the logo is anchored. Community and Pro both support all four corners, using the same position on screen and in image exports.

| Item | Value |
| --- | --- |
| JavaScript property | `brandPosition` |
| HTML attribute | `brand-position` |
| Type | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` |
| Default | `'bottom-right'` |
| Allowed values | `top-left`, `top-right`, `bottom-left`, `bottom-right` |

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

### color

Set endpoint colors as [first, second].

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

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

### lineColor

Connector (bar) stroke colour — its own faint default, independent of the `color` pair.

| Item | Value |
| --- | --- |
| JavaScript property | `lineColor` |
| HTML attribute | `line-color` |
| Type | `string` |
| Default | `'#cbd5e1'` |

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

### lineWidth

Connector width in CSS px.

| Item | Value |
| --- | --- |
| JavaScript property | `lineWidth` |
| HTML attribute | `line-width` |
| Type | `number` |
| Default | `3` |

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

### marker

Marker glyph. Polymorphic (like `color`): a single symbol applies to BOTH ends; an array or comma-string is read as `[lowMarker, highMarker]` (a single token leaves the low end on `'circle'` and applies the token to the high end, mirroring the pair rule). Resolved once via `resolvePair`. Per-datum `DumbbellDatum.lowMarker`/`highMarker` override this for individual dumbbells.

| Item | Value |
| --- | --- |
| JavaScript property | `marker` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `DumbbellMarkerSymbol \| string \| ReadonlyArray<string>` |
| Default | `'circle'` |

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

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

### markerSize

Marker radius in CSS px.

| Item | Value |
| --- | --- |
| JavaScript property | `markerSize` |
| HTML attribute | `marker-size` |
| Type | `number` |
| Default | `6` |

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

### sortDescending

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

| Item | Value |
| --- | --- |
| JavaScript property | `sortDescending` |
| HTML attribute | `sort-descending` |
| Type | `boolean` |
| Default | `false` |

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

### valueAxisLabel

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

| Item | Value |
| --- | --- |
| JavaScript property | `valueAxisLabel` |
| HTML attribute | `value-axis-label` |
| 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-xAxis"></a>

### xAxis

Configure the horizontal axis type, categories, range, and formatting. For a category axis, match the categories order to the value array indices. Charts supporting multiple axes can accept an axis array.

| Item | Value |
| --- | --- |
| JavaScript property | `xAxis` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `CartesianAxisInput \| ReadonlyArray<CartesianAxisInput>` |
| Default | `undefined` |
| Literals in the type | `auto`, `off` |

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

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

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

### yAxis

Configure the vertical axis range, ticks, labels, and direction. Use consistent units for comparisons, and consider a zero baseline when comparing bar lengths.

| Item | Value |
| --- | --- |
| JavaScript property | `yAxis` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `CartesianAxisInput` |
| Default | `undefined` |
| Literals in the type | `auto`, `off` |

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

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

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

### gridLines

Allowed values: auto, off. Default: undefined.

| Item | Value |
| --- | --- |
| JavaScript property | `gridLines` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `CartesianGridLinesInput` |
| Default | `undefined` |
| Literals in the type | `auto`, `off` |

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

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

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

### xLabelMode

How crowded category-axis labels are decluttered. Default 'auto' thins labels horizontally.

| Item | Value |
| --- | --- |
| JavaScript property | `xLabelMode` |
| HTML attribute | `x-label-mode` |
| Type | `'auto' \| 'all' \| 'thin' \| 'rotate' \| 'none'` |
| Default | `undefined` |
| Allowed values | `none`, `auto`, `all`, `thin`, `rotate` |

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

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

### xLabelRotation

Explicit category-label rotation in degrees (respected as a floor).

| Item | Value |
| --- | --- |
| JavaScript property | `xLabelRotation` |
| HTML attribute | `x-label-rotation` |
| 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-xLabelMaxCount"></a>

### xLabelMaxCount

Hard cap on the number of category labels shown.

| Item | Value |
| --- | --- |
| JavaScript property | `xLabelMaxCount` |
| HTML attribute | `x-label-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-crosshair"></a>

### crosshair

Crosshair that follows the cursor across the plot. `true`/`'auto'` enables a snapping line; pass an object to set mode/snap/color/dash.

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

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

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

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

### chartTitle

The title inside the chart. Explain the data's unit and meaning alongside it.

| Item | Value |
| --- | --- |
| JavaScript property | `chartTitle` |
| HTML attribute | `chart-title` |
| 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-chartSubtitle"></a>

### chartSubtitle

The subtitle inside the chart.

| Item | Value |
| --- | --- |
| JavaScript property | `chartSubtitle` |
| HTML attribute | `chart-subtitle` |
| 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-legend"></a>

### legend

Show the low/high legend. When `false` no legend renders and its reserved space is reclaimed.

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

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

### legendPosition

Edge the low/high legend attaches to. Default `'top'`.

| Item | Value |
| --- | --- |
| JavaScript property | `legendPosition` |
| HTML attribute | `legend-position` |
| Type | `DumbbellChartLegendPosition` |
| Default | `'top'` |
| Allowed values | `top`, `bottom`, `left`, `right` |

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

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

### tooltipEnabled

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

| Item | Value |
| --- | --- |
| JavaScript property | `tooltipEnabled` |
| HTML attribute | `tooltip-show` |
| Type | `boolean` |
| Default | `true` |

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

### tooltipFormat

Pass as a JavaScript property. type: (detail: DumbbellChartPointerEventDetail) => string.

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

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

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

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

### tooltip

Rich tooltip configuration (matches the line/lollipop family). Pass an object to set `show`/`mode`/`side`/`format`/`html`/`style`/`connector`/`draggable`/`interactive`/`trigger`/`openMode`. The legacy `tooltipEnabled`/`tooltipFormat` props remain the fallback when `tooltip` is omitted. The hit is the dumbbell PAIR (low+high) under the cursor; the default text is `category: low → high`.

| Item | Value |
| --- | --- |
| JavaScript property | `tooltip` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `CartesianTooltipInput` |
| Default | `undefined` |
| Literals in the type | `auto`, `off` |

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

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

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

### enableMouseTracking

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

| Item | Value |
| --- | --- |
| JavaScript property | `enableMouseTracking` |
| HTML attribute | `enable-mouse-tracking` |
| Type | `boolean` |
| Default | `true` |

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

### animated

Whether to animate initial display and data changes.

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

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

### animationDuration

Animation duration in milliseconds.

| Item | Value |
| --- | --- |
| JavaScript property | `animationDuration` |
| HTML attribute | `animation-duration` |
| Type | `number` |
| Default | `600` |

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

### animationEasing

Allowed values: linear, ease-out, ease-in, ease-in-out. Default: 'ease-out'.

| Item | Value |
| --- | --- |
| JavaScript property | `animationEasing` |
| HTML attribute | `animation-easing` |
| Type | `DumbbellChartEasing` |
| Default | `'ease-out'` |
| Allowed values | `linear`, `ease-out`, `ease-in`, `ease-in-out` |

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

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

### animationType

Allowed values: initial, update. Default: undefined.

| Item | Value |
| --- | --- |
| JavaScript property | `animationType` |
| HTML attribute | `animation-type` |
| Type | `DumbbellChartAnimationType` |
| Default | `undefined` |
| Allowed values | `initial`, `update` |

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

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

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

### streamSource

A stream source for live data. Check the contract for the specific type.

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

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

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

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

### streamWindow

The streaming data range to keep visible.

| Item | Value |
| --- | --- |
| JavaScript property | `streamWindow` |
| HTML attribute | `stream-window` |
| 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-streamMax"></a>

### streamMax

The maximum number of streaming data points to retain.

| Item | Value |
| --- | --- |
| JavaScript property | `streamMax` |
| HTML attribute | `stream-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-engine"></a>

### engine

Renderer selection: auto, standard, or pro. Engine selection is separate from permission to use a Pro chart type.

| Item | Value |
| --- | --- |
| JavaScript property | `engine` |
| HTML attribute | `engine` |
| Type | `DumbbellChartEngineMode` |
| Default | `'auto'` |
| Allowed values | `auto`, `standard`, `pro` |

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

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

### proThreshold

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

| Item | Value |
| --- | --- |
| JavaScript property | `proThreshold` |
| HTML attribute | `pro-threshold` |
| Type | `number` |
| Default | `50_000` |

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

### unavailable

Allowed values: fallback, error, throw. Default: 'fallback'.

| Item | Value |
| --- | --- |
| JavaScript property | `unavailable` |
| HTML attribute | `unavailable` |
| Type | `DumbbellChartUnavailableBehaviour` |
| Default | `'fallback'` |
| Allowed values | `fallback`, `error`, `throw` |

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

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

## Events

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

### rendered

Emits rendering results in detail when chart drawing completes.

Event name: `rendered`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<DumbbellChartRenderResult & { tier: DumbbellChartEngineTier }>`.

```javascript
chart.addEventListener('rendered', event => {
  console.log(event.detail); // DumbbellChartRenderResult & { tier: DumbbellChartEngineTier }
});
```

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

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

### pointClick

A point selection event. Read the selected data and index from CustomEvent.detail.

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

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

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

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

### pointHover

CustomEvent.detail type: DumbbellChartPointerEventDetail | null. Event names are case-sensitive.

Event name: `pointHover`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<DumbbellChartPointerEventDetail | null>`.

```javascript
chart.addEventListener('pointHover', event => {
  console.log(event.detail); // DumbbellChartPointerEventDetail | null
});
```

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

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

### crosshairMove

CustomEvent.detail type: CartesianCrosshairEventDetail | null. Event names are case-sensitive.

Event name: `crosshairMove`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<CartesianCrosshairEventDetail | null>`.

```javascript
chart.addEventListener('crosshairMove', event => {
  console.log(event.detail); // CartesianCrosshairEventDetail | null
});
```

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

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

### pointContextMenu

CustomEvent.detail type: ChartPointContextMenuEventDetail<DumbbellChartPointerEventDetail>. Event names are case-sensitive.

Event name: `pointContextMenu`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<ChartPointContextMenuEventDetail<DumbbellChartPointerEventDetail>>`.

```javascript
chart.addEventListener('pointContextMenu', event => {
  console.log(event.detail); // ChartPointContextMenuEventDetail<DumbbellChartPointerEventDetail>
});
```

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

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

### appended

CustomEvent.detail type: { count: number }. Event names are case-sensitive.

Event name: `appended`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<{ count: number }>`.

```javascript
chart.addEventListener('appended', event => {
  console.log(event.detail); // { count: number }
});
```

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

### windowSlid

CustomEvent.detail type: { dropped: number }. Event names are case-sensitive.

Event name: `windowSlid`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<{ dropped: number }>`.

```javascript
chart.addEventListener('windowSlid', event => {
  console.log(event.detail); // { dropped: number }
});
```

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

### chartAnimationStart

CustomEvent.detail type: void. Event names are case-sensitive.

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

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

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

### chartAnimationEnd

CustomEvent.detail type: void. Event names are case-sensitive.

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

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

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

### chartAnimationInterrupted

CustomEvent.detail type: void. Event names are case-sensitive.

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

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

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

### tooltipShow

Whether to display the built-in tooltip.

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

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

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

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

### tooltipHide

CustomEvent.detail type: void. Event names are case-sensitive.

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

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

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

### tooltipAction

CustomEvent.detail type: CartesianTooltipActionEventDetail. Event names are case-sensitive.

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

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

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

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

### seriesOutsideClick

CustomEvent.detail type: CartesianSeriesOutsideClickEventDetail. Event names are case-sensitive.

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

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

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

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

### legendItemClick

CustomEvent.detail type: DumbbellChartLegendItemEventDetail. Event names are case-sensitive.

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

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

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

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

### seriesToggled

CustomEvent.detail type: DumbbellChartSeriesToggledEventDetail. Event names are case-sensitive.

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

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

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

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

## Methods

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

### redraw

Redraw the chart using its current data and options. Inspect the rendered result after the returned Promise resolves.

```typescript
redraw(): Promise<DumbbellChartRenderResult>
```

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

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

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

### getActiveTier

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

```typescript
getActiveTier(): Promise<DumbbellChartEngineTier>
```

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

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

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

### setData

Replace the bar set.

```typescript
setData(data: ReadonlyArray<DumbbellDatum>): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `data` | `ReadonlyArray<DumbbellDatum>` | Required |

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

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

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

### appendPoint

Append one value to the stream. Check the argument type and the licensing requirements for streaming.

```typescript
appendPoint(datum: DumbbellDatum): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `datum` | `DumbbellDatum` | Required |

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

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

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

### appendBatch

Append multiple values to the stream. Check the argument type and the licensing requirements for streaming.

```typescript
appendBatch(data: ReadonlyArray<DumbbellPairDatum>): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `data` | `ReadonlyArray<DumbbellPairDatum>` | Required |

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

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

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

### shift

Drop the oldest streamed categories (the `data` boxes are not the stream).

```typescript
shift(count: number): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `count` | `number` | Required |

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

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

### replace

Swap the streamed set (`replace([])` clears it); the base `values` never leave. Without `chart.streaming` the dies upsert into the base like a batch (quietly: no `appended`, no `binChanged`, as a ring replace).

```typescript
replace(data: ReadonlyArray<DumbbellPairDatum>): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `data` | `ReadonlyArray<DumbbellPairDatum>` | Required |

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

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

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

### getStreamSource

The stream session's source (Chart Pro): like the stream methods it waits for a license still being confirmed.

```typescript
getStreamSource(): Promise<DumbbellChartStreamSource | undefined>
```

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

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

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

### showSeries

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

```typescript
showSeries(idOrIndex: string | number, opts?: { redraw?: boolean }): Promise<boolean>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `idOrIndex` | `string \| number` | Required |
| `opts` | `{ redraw?: boolean }` | Optional |

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

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

### hideSeries

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

```typescript
hideSeries(idOrIndex: string | number, opts?: { redraw?: boolean }): Promise<boolean>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `idOrIndex` | `string \| number` | Required |
| `opts` | `{ redraw?: boolean }` | Optional |

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

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

### setAnimation

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

```typescript
setAnimation(options: { duration?: number; easing?: DumbbellChartEasing; enabled?: boolean; type?: DumbbellChartAnimationType }): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `options` | `{ duration?: number; easing?: DumbbellChartEasing; enabled?: boolean; type?: DumbbellChartAnimationType }` | Required |

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

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

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

### pauseAnimation

Pause the current animation.

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

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

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

### resumeAnimation

Resume a paused animation.

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

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

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

### replayAnimation

Replay the initial sweep from min → value(s). No-op when animation is off / reduced.

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

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

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

### hitTest

The box under a host-local CSS point (the nearest slot, within half a pitch), or null.

```typescript
hitTest(cssX: number, cssY: number): Promise<DumbbellChartPointerEventDetail | null>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `cssX` | `number` | Required |
| `cssY` | `number` | Required |

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

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

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

### showTooltipAtPoint

Open the tooltip for a dot programmatically. `pointIndex` is the category (row) index; the optional `seriesIndex` selects a group within that row (defaults to the first visible group's dot in the row). Returns the emitted tooltip detail, or null when no dot resolves / the tooltip is disabled.

```typescript
showTooltipAtPoint(index: number): Promise<CartesianTooltipEventDetail | null>
```

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

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

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

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

### hideTooltip

Close the currently visible tooltip.

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

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

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

### getEngineStatus

Requested engine vs what runs, and why (CHART-ADD-08): always Standard (this type has no WebGPU renderer); read without side effects, never consults the license.

```typescript
getEngineStatus(): Promise<ChartEngineStatus>
```

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

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