Skip to main content

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.

Scale by axis


- Scroll to zoom: Use the mouse scroll wheel.


Scale by mouse scroll with X


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


Scale by by mouse scroll with X and Y

Panning​

Panning shifts the chart horizontally or vertically.

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

Scale by by mouse scroll with X and Y

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
Horizontal Ray styled example

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: Reset the viewport with doBasicScale() (see Basic scale)

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 },
}
  1. 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.

Basic scale​

chart.chartModel.doBasicScale() resets the visible range to the default viewport and redraws the chart.

  • X-axis: the last scale.defaultViewportItems candles (default 100). If the series has fewer candles, all of them are shown. The range ends after the last candle, plus the right offset.
  • Y-axis: the price range is fitted to the data in that viewport.

If the main series has no candles, the call does nothing.

Call it after you set candle data when you want the chart to show the latest candles at the default zoom:

chart.setData({
	candles,
	instrument,
});
chart.chartModel.doBasicScale();

The same reset runs when the user double-clicks or double-taps the X axis, and when you call chart.chartComponent.resetChartScale().

Change how many candles the reset shows:

scale: {
	defaultViewportItems: 25,
}

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

Property
Description
Type

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

zoomSensitivity

{ /** * Value is related to zoom event (zooming chart via mouse wheel) * 0..1 ratio of full viewport; 0.5 = middle, 0.75 = 3/4 of viewport * This value is also related to touchpad. * Touchpad sensitivity is dynamic, and based on delta distance event: * - if distance is small, zoom sencitivity is minimal, which allows you to zoom in/out on the chart and view each candle in details * - if distance is big, zoom sencitivity is becomes close to the config value below, which allows you to zoom in/out on the chart and quickly change zoom with big sensitivity */ wheel: number; }

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

Property
Description
Type

legend

{ opened: boolean; showOHLC: boolean; showPriceChange: boolean; showVolume: boolean; showInstrument: boolean; showPeriod: boolean; mode: LegendMode; }

sessionBreaks

{ visible: boolean; }

extendedHours

{ visible: boolean; }

timeframeChangeStrategy

deprecated, will be removed in v6, use viewportStrategy instead
{ aggregations: TimeframeChangeStrategy; instrument: TimeframeChangeStrategy; }

viewportStrategy

optional, to support backward compability with timeframeChangeStrategy
{ aggregations?: ViewportStrategy; instrument?: ViewportStrategy; }

trading

{ visible: boolean; showOrders: boolean; showPositions: boolean; executedOrders: { enabled: boolean; displayMode: ExecutedOrdersDisplayMode; }; bounds: { min: number; max: number; }; rightOffset: number; quantity: OrderQuantity; quantityPrecision: number; quantityStep: number; minQuantity: number; maxQuantity: number; }

candlesData

{ price: PriceType; candleAlignment: CandleAlignment; }

aggregationPeriod

{ applyUponCreation: boolean; }

scale

{ fit: { studies: boolean; orders: boolean; positions: boolean; }; }