Scaling

Scaling adjusts the visible chart range along the X and Y axes.

User interactions

You can scale the chart in several ways:

• Drag the axis: Click and drag the X or Y axis.

- Scroll to zoom: Use the mouse scroll wheel.

- Scale both axes: Enable lockPriceToBarRatio to zoom X and Y simultaneously.

Panning

Panning shifts the chart horizontally or vertically.

Press and hold the left mouse button, then drag the chart:

Scale History

chart's ScaleModel has a public history property, which is used to store history of applied scales.

This store is stack-like data structure and the elements are ScaleHistoryItem's.

export interface ScaleHistoryItem {
    xStart: Unit;
    xEnd: Unit;
    yStart: Unit;
    yEnd: Unit;
}

Use the following methods from ScaleModel to access and manipulate scale history:

export class ScaleModel {
    // removes from the stack the last ScaleHistoryItem
    public popFromHistory(): ScaleHistoryItem | undefined {
        return;
    }
    // pushes to the stack new ScaleHistoryItem
    public pushToHistory(item: ScaleHistoryItem): void {}
    // removes all the elements from the history
    public clearHistory(): void {}
}

Example

export function scaleHistoryExample(scale: ScaleModel) {
    const historyItem = scale.popFromHistory();
    if (historyItem) {
        scale.pushToHistory(historyItem);
        scale.clearHistory();
    }
}

---

Configuration options

Disable auto-scale on drag

To disable auto-scaling during long vertical drags using the AutoScaleDisableOnDrag interface:

export interface AutoScaleDisableOnDrag {
    enabled: boolean;
    /**
     * The angle of mouse movement. Default - Math.PI / 9.
     */
    edgeAngle: number;
    /**
     * Distance that mouse should travel vertically in px. Default - 80.
     */
    yDiff: number;
}

Behavior

The ChartAreaPanHandler disables auto-scaling if all of the following conditions are true:

1. AutoScaleDisableOnDrag.enabled === true
2. AutoScaleDisableOnDrag.edgeAngle > α
3. AutoScaleDisableOnDrag.yDiff > AB length

Candles viewport

You can control how many candles are displayed using the viewportStrategy option in ChartConfig.

Available strategies:

• timeframe: Preserve the selected timeframe
• candles: Maintain a fixed number of candles
• basic: Use default scaling behavior

API axis range

To set a fixed Y or X range instead of auto-scaling:

1. Disable auto-scale in initialChartConfig (React) or chart config (lite). Also set autoScaleOnCandles: false — otherwise the chart re-enables auto-scale when candles are loaded:

initialChartConfig: {
	scale: { auto: false, autoScaleOnCandles: false },
}

2. After candles are loaded, set the range programmatically on the chart instance (chart from createChart / chart API):

• Y-axis (price units): chart.scale.setYScale(yStart, yEnd)
• X-axis (candle index units): chart.data.setXScale(xStart, xEnd)
• X-axis (timestamps): chart.data.setTimestampRange(startTimestamp, endTimestamp)

Subscribe to chart.data.observeCandlesChanged() so the scale is applied after the initial candle data is set. If scale.auto is still true, setYScale / setXScale will run auto-scaling again and override your values.

Scroll limits

Panning past the first or last candle is constrained by components.chart.minCandlesOffset (default 2).

initialChartConfig: {
  components: {
    chart: { minCandlesOffset: 5 }, // stricter edge — less empty space beyond candles
  },
},

For custom rules, add your own constraint in onChartCreated:

chart.scale.addXConstraint((initialState, state) => {
  // return modified state — see candleEdgesConstrait in chart-core for reference
  return state;
});

Set scale.disableAnimations: true to turn off viewport pan/zoom animation (including when the last candle updates).

Chart scale configuration

ChartScale auto Auto scale will always fit whole chart series in viewport. boolean zoomToCursor True - will zoom to cursor on mouse wheel. False - zoom to last candle. boolean lockPriceToBarRatio Locks the ratio between price/time, so when zooming it will feel like google maps. boolean inverse Inverses the Y scale vertically. boolean autoScaleOnCandles Do auto scale (even if it's not enabled in config) after instrument change. boolean autoScaleDisableOnDrag When dragging chart under specific angle - will automatically disable auto-scale. AutoScaleDisableOnDrag enabled boolean edgeAngle The angle of mouse movement. Default - Math.PI / 9. number yDiff Distance that mouse should travel vertically in px. Default - 80. number zoomSensitivity ChartScale_zoomSensitivity defaultViewportItems Defines how much items (candles) will be in viewport when chart applies basic scale number keepZoomXOnYAxisChange Adjust x viewport when y-axis width is changed, so x zoom remains the same boolean disableAnimations Disable all scale process animations boolean

React viewport configuration

ChartReactSettings legend ChartReactSettings_legend sessionBreaks ChartReactSettings_sessionBreaks extendedHours ChartReactSettings_extendedHours timeframeChangeStrategy deprecated, will be removed in v6, use viewportStrategy instead ChartReactSettings_timeframeChangeStrategy viewportStrategy optional, to support backward compability with timeframeChangeStrategy ChartReactSettings_viewportStrategy trading ChartReactSettings_trading candlesData ChartReactSettings_candlesData aggregationPeriod ChartReactSettings_aggregationPeriod scale ChartReactSettings_scale