Changing the Interval

The interval is the time each candle covers: one minute, six hours, one day, and so on. Intervals are values of the CandleInterval enum, e.g. CandleInterval.SIX_HOURS. Which intervals you can use depends on the exchange: see Which Intervals an Exchange Supports.

SciFinanceChart.changeInterval

changeInterval is a method of SciFinanceChart, the chart you reach through financeChartPanel.financeApi. It reloads the current symbol at the new candle size, and lands on a period in the same step.

/**
 * Reload the current symbol's candles at a new interval, landing on a period in the same step.
 *
 * `period` picks what the chart shows at the new interval:
 *  - a {@link TPeriod} — that period, applied at the new interval;
 *  - `null` — no period (free pan/zoom). The view lands on the interval's default window, but
 *    nothing caps the zoom afterwards;
 *  - omitted — {@link defaultPeriodForInterval}, even when no period was active before.
 *
 * Afterwards {@link currentPeriod} describes what is on screen, so there is no need to follow
 * this with {@link setPeriod}. The fetch is sized for the target period, so a period change
 * costs no second fetch. To keep the user's period across the switch instead of snapping to
 * the default, pass `carryPeriodToInterval(chart.currentPeriod, interval)`.
 *
 * A {@link setPeriod} call made while this is loading wins: the period resolved here is then
 * not applied.
 */
changeInterval(interval: CandleInterval, period?: TPeriod | null): Promise<void>;

import { CandleInterval } from "scichart-scitrader";

const chart = financeChartPanel.financeApi; // SciFinanceChart

// Switch to daily candles. With no period given, the chart shows the
// interval's default period: a year, for daily candles
await chart.changeInterval(CandleInterval.ONE_DAY);

// Switch to daily candles and show the last month
await chart.changeInterval(CandleInterval.ONE_DAY, "1M");

// Switch to daily candles with no period: the user can pan and zoom freely
await chart.changeInterval(CandleInterval.ONE_DAY, null);

The CandleInterval enum

enum CandleInterval {
    ONE_SECOND = "1s",
    ONE_MINUTE = "1m",
    THREE_MINUTES = "3m",
    FIVE_MINUTES = "5m",
    FIFTEEN_MINUTES = "15m",
    THIRTY_MINUTES = "30m",
    ONE_HOUR = "1h",
    TWO_HOURS = "2h",
    FOUR_HOURS = "4h",
    SIX_HOURS = "6h",
    EIGHT_HOURS = "8h",
    TWELVE_HOURS = "12h",
    ONE_DAY = "1d",
    THREE_DAYS = "3d",
    ONE_WEEK = "1w",
    ONE_MONTH = "1M"
}

The second argument picks the period:

period	What the chart shows
Omitted	The new interval's default period, even if no period was set before
A period, e.g. "1M"	That period, at the new interval
null	No period. The view starts on the interval's default span, but nothing holds it there, so the user can pan and zoom freely

Afterwards chart.currentPeriod reports what is on screen, so there is no need to call setPeriod as well.

defaultPeriodForInterval: The Default Period for Each Interval

Each interval has a default period: a span that shows a useful number of candles at that size. A week of 1-minute candles would be over 10,000 candles, while a week of daily candles would be just seven, so the default grows with the interval. defaultPeriodForInterval(interval) returns it.

changeInterval uses it when you don't pass a period. Call it yourself when you need to know where an interval change will land, for example to:

• Start the chart on the same period an interval change would give, in the chart config.
• Tell the user what they'll see, e.g. in an interval button's tooltip.
• Update your own period picker when the interval changes, so it shows the right period.

The defaults for the intervals Coinbase supports:

Interval	Default period
ONE_MINUTE (1m)	"1H", an hour
FIVE_MINUTES (5m)	"1D", a day
FIFTEEN_MINUTES (15m)	"5D", five days
ONE_HOUR (1h)	"1W", a week
SIX_HOURS (6h)	"3M", three months
ONE_DAY (1d)	"1Y", a year

import {
    CandleInterval,
    CoinbaseExchange,
    defaultPeriodForInterval,
    ISciFinanceChartPanelConfig,
    OHLCStudy,
    VolumeStudy
} from "scichart-scitrader";

// The period changeInterval(CandleInterval.ONE_HOUR) would land on: "1W"
const period = defaultPeriodForInterval(CandleInterval.ONE_HOUR);

// Start a chart on 1h candles with that same period, so the first view
// matches what an interval change to 1h would show
const config: ISciFinanceChartPanelConfig = {
    exchangeName: CoinbaseExchange.name,
    symbol: "BTC-USD",
    interval: CandleInterval.ONE_HOUR,
    period, // "1W"
    studies: [new OHLCStudy(), new VolumeStudy()],
};

// Label an interval button with where it will land
const button = document.createElement("button");
button.textContent = "6h";
button.title = `Shows ${defaultPeriodForInterval(CandleInterval.SIX_HOURS)} of 6h candles`; // "Shows 3M of 6h candles"

The defaultPeriodForInterval function, with its TSDoc

/**
 * Default preset period for an interval — looked up from the static
 * {@link DEFAULT_PERIOD_FOR_INTERVAL} table.
 */
function defaultPeriodForInterval(interval: CandleInterval): TPeriod;

What Happens When the Interval Changes

changeInterval works like a symbol change, but keeps the symbol:

1. The chart raises dataLoadStarted and covers the old candles with its loading overlay.
2. The candles are fetched once, sized for the period. The request reads from the candle store first, and asks the exchange only for what is missing.
3. The chart redraws. Studies recalculate on the new candles, the view lands on the period, and the chart raises dataRenderComplete with type: "interval-change".
4. Live updates continue at the new interval.

caution

Only pass an interval the exchange supports. With an interval it doesn't support, such as CandleInterval.FOUR_HOURS on Coinbase, the chart has no candles to load and stays on its loading overlay. Check getSupportedIntervals() first. The IntervalSelector's default list includes intervals some exchanges don't have, so pass it the exchange's supported intervals.

Which Intervals an Exchange Supports: getSupportedIntervals

Each exchange supports its own intervals. Coinbase, for example, offers 1m, 5m, 15m, 1h, 6h and 1d candles. Every exchange lists its own with getSupportedIntervals():

import { CoinbaseExchange, defaultExchangeProvider } from "scichart-scitrader";

// Look up a registered exchange by its name, and ask which intervals it supports
const intervals = defaultExchangeProvider.getExchange(CoinbaseExchange.name).getSupportedIntervals();
// e.g. [ONE_MINUTE, FIVE_MINUTES, FIFTEEN_MINUTES, ONE_HOUR, SIX_HOURS, ONE_DAY]

IRemoteExchange.getSupportedIntervals, with its TSDoc

/**
 * The set of {@link CandleInterval} values the adapter supports. Drives
 * the UI's interval picker — pickers filter their hardcoded option lists
 * to this set, hiding intervals the active provider can't serve.
 *
 * Implementations typically derive the list from the shared
 * `intervalMaps` registry via `getSupportedIntervalsFor(name)`.
 */
getSupportedIntervals(): CandleInterval[];

To let the user pick an interval, build your buttons from this list, as the example below does, or use the ready-made IntervalSelector and pass it these intervals.

Keeping the User's Span with carryPeriodToInterval

Without a period, changeInterval jumps to the new interval's default period. To keep roughly the span the user was looking at instead, pass the result of carryPeriodToInterval:

import { CandleInterval, carryPeriodToInterval } from "scichart-scitrader";

// The period the user is looking at now, e.g. "1M", or null for none
const current = chart.currentPeriod;

// The closest period that suits the new interval.
// "1M" at 1h candles stays "1M"; "1W" at 1m candles is cut to "1D"
const period = carryPeriodToInterval(current, CandleInterval.ONE_HOUR);

// Change the interval and land on that period, in one load
await chart.changeInterval(CandleInterval.ONE_HOUR, period);

carryPeriodToInterval(period, interval) returns:

• The same period, when it suits the new interval.
• A shorter period, when the period is longer than the interval allows, e.g. a week of 1m candles becomes a day.
• A longer period, when the period would show fewer than 20 candles, e.g. a day of 1w candles becomes six months.
• null for null, so a chart with no period keeps none.

The carryPeriodToInterval function, with its TSDoc

/**
 * The period to keep when the interval changes, so the view stays roughly the same span instead
 * of snapping to {@link defaultPeriodForInterval}. Pass the result to
 * `SciFinanceChart.changeInterval(interval, period)`.
 *
 * - `null` (no period, free pan/zoom) stays `null`.
 * - A period longer than {@link maxAllowedPeriodForInterval} for the new interval is cut to that
 *   maximum, e.g. `1W` at `1m` candles becomes `1D`.
 * - A period that would show fewer than {@link MIN_CARRIED_PERIOD_CANDLES} candles steps up to the
 *   shortest longer preset that shows enough, e.g. `1D` at `1w` candles becomes `6M`.
 * - Otherwise the period is kept.
 *
 * `ALL` is treated as longer than every other preset, and kept when the interval allows it.
 * `YTD` is kept unless it is too short (early in the year at coarse intervals).
 *
 * @param period - the period in effect before the change, or `null`.
 * @param interval - the interval being changed to.
 * @param nowMs - the time periods are measured back from. Defaults to `Date.now()`.
 */
function carryPeriodToInterval(period: TPeriod | null, interval: CandleInterval, nowMs?: number): TPeriod | null;

TypeScript Example: Keeping the Span with carryPeriodToInterval

This chart starts on 1h candles over the last month. Click an interval with Keep the span ticked, and the chart keeps about a month on screen, using carryPeriodToInterval. Untick it, and each interval jumps to its default period instead. The toolbar shows the interval and period after each change.

The code for this example is found below.

TS

import "scichart-scitrader/scitrader.css";
import {
    CandleInterval,
    carryPeriodToInterval,
    CoinbaseExchange,
    defaultExchangeProvider,
    idbPriceStore,
    OHLCStudy,
    SciFinanceChartPanel,
    TPeriod,
    VolumeStudy,
} from "scichart-scitrader";

// This example expects this HTML:
// <div style="display: flex; flex-direction: column; height: 100%">
//     <div id="toolbar"></div>
//     <div id="chart" style="flex: 1; min-height: 0"></div>
// </div>

// Register a data source, once, at app startup
defaultExchangeProvider.registerExchange(CoinbaseExchange, idbPriceStore);

// Coinbase offers 1m, 5m, 15m, 1h, 6h and 1d candles
const INTERVALS = [CandleInterval.FIFTEEN_MINUTES, CandleInterval.ONE_HOUR, CandleInterval.SIX_HOURS, CandleInterval.ONE_DAY];

async function createChart() {
    const toolbar = document.getElementById("toolbar");
    Object.assign(toolbar.style, toolbarStyle);

    let currentInterval = CandleInterval.ONE_HOUR;
    const financeChartPanel = await SciFinanceChartPanel.create(document.getElementById("chart"), {
        exchangeName: CoinbaseExchange.name, // name="Coinbase" matches the built-in CoinbaseExchange
        symbol: "BTC-USD",
        interval: currentInterval,
        period: "1M", // start on the last month
        studies: [new OHLCStudy(), new VolumeStudy()],
    });
    const chart = financeChartPanel.financeApi; // SciFinanceChart

    // A checkbox to compare the two behaviours
    const keepSpanLabel = document.createElement("label");
    const keepSpan = document.createElement("input");
    keepSpan.type = "checkbox";
    keepSpan.checked = true;
    keepSpanLabel.append(keepSpan, " Keep the span (carryPeriodToInterval)");
    Object.assign(keepSpanLabel.style, labelStyle);

    const buttons = INTERVALS.map((interval) => {
        const button = document.createElement("button");
        button.textContent = interval; // "15m", "1h", "6h", "1d"
        button.onclick = () => {
            currentInterval = interval;
            // Checked: keep about the span the user is looking at, adjusted to suit the new interval.
            // Unchecked: pass no period, so the chart jumps to the interval's default period
            const period: TPeriod | null | undefined = keepSpan.checked
                ? carryPeriodToInterval(chart.currentPeriod, interval)
                : undefined;
            chart.changeInterval(interval, period);
        };
        toolbar.appendChild(button);
        return button;
    });
    toolbar.appendChild(keepSpanLabel);

    // Shows the interval and period on screen
    const status = document.createElement("span");
    Object.assign(status.style, labelStyle);
    toolbar.appendChild(status);

    const updateToolbar = (loading: boolean) => {
        buttons.forEach((button, i) => {
            Object.assign(button.style, buttonStyle(INTERVALS[i] === currentInterval));
            button.disabled = loading;
        });
        status.textContent = loading ? "Loading…" : `Interval ${currentInterval}, period ${chart.currentPeriod}`;
    };
    updateToolbar(false);

    // Disable the buttons while an interval change loads, and show the result once it's drawn
    chart.dataLoadStarted.subscribe(() => updateToolbar(true));
    chart.dataRenderComplete.subscribe((args) => {
        if (args.type === "interval-change") {
            updateToolbar(false);
        }
    });

    return financeChartPanel; // call financeChartPanel.cleanup() when the page goes away
}

// The toolbar uses SciTrader's UI colours: its --st-ui-* CSS variables, with the stylesheet's defaults
const toolbarStyle: Partial<CSSStyleDeclaration> = {
    display: "flex",
    flexWrap: "wrap",
    alignItems: "center",
    gap: "8px",
    padding: "8px",
    background: "var(--st-ui-background, #2b2839)",
    borderBottom: "1px solid var(--st-ui-divider, rgba(255,255,255,0.1))",
};

const buttonStyle = (active: boolean): Partial<CSSStyleDeclaration> => ({
    padding: "6px 14px",
    fontSize: "14px",
    fontFamily: "var(--st-font-family, sans-serif)",
    color: "var(--st-ui-text, #ffffff)",
    background: active ? "var(--st-ui-accent, #7464ff)" : "var(--st-ui-surface, #373447)",
    border: "1px solid var(--st-ui-divider, rgba(255,255,255,0.1))",
    borderRadius: "4px",
    cursor: "pointer",
});

const labelStyle: Partial<CSSStyleDeclaration> = {
    marginLeft: "8px",
    fontSize: "14px",
    fontFamily: "var(--st-font-family, sans-serif)",
    color: "var(--st-ui-text, #ffffff)",
};

createChart();

TypeScript Example: Changing the Interval

This example puts the topics on this page together, in plain TypeScript:

• The interval buttons come from getSupportedIntervals(), so they offer only intervals Coinbase can serve.
• Each button calls changeInterval(interval) with no period, so the chart lands on the interval's default period.
• Each button's tooltip uses defaultPeriodForInterval to say what the user will see.
• dataLoadStarted and dataRenderComplete disable the buttons while the candles load, and update the status line once they're drawn.

The code for this example is found below.

TS

import "scichart-scitrader/scitrader.css";
import {
    CandleInterval,
    CoinbaseExchange,
    defaultExchangeProvider,
    defaultPeriodForInterval,
    idbPriceStore,
    OHLCStudy,
    SciFinanceChartPanel,
    VolumeStudy,
} from "scichart-scitrader";

// This example expects this HTML:
// <div style="display: flex; flex-direction: column; height: 100%">
//     <div id="toolbar"></div>
//     <div id="chart" style="flex: 1; min-height: 0"></div>
// </div>

// Register a data source, once, at app startup
defaultExchangeProvider.registerExchange(CoinbaseExchange, idbPriceStore);

async function createChart() {
    const toolbar = document.getElementById("toolbar");
    Object.assign(toolbar.style, toolbarStyle);

    let currentInterval = CandleInterval.ONE_HOUR;
    const financeChartPanel = await SciFinanceChartPanel.create(document.getElementById("chart"), {
        exchangeName: CoinbaseExchange.name, // name="Coinbase" matches the built-in CoinbaseExchange
        symbol: "BTC-USD",
        interval: currentInterval,
        // Start on the same period changeInterval would land on: a week, for 1h candles
        period: defaultPeriodForInterval(currentInterval),
        studies: [new OHLCStudy(), new VolumeStudy()],
    });
    const chart = financeChartPanel.financeApi; // SciFinanceChart

    // Ask the exchange which intervals it supports, so every button works.
    // Coinbase supports 1m, 5m, 15m, 1h, 6h and 1d
    const intervals = defaultExchangeProvider.getExchange(CoinbaseExchange.name).getSupportedIntervals();

    // One button per supported interval
    const buttons = intervals.map((interval) => {
        const button = document.createElement("button");
        button.textContent = interval; // CandleInterval values are short labels: "1m", "1h", "1d", ...
        // Tell the user which period the chart will land on
        button.title = `Shows ${defaultPeriodForInterval(interval)} of ${interval} candles`;
        button.onclick = () => {
            currentInterval = interval;
            // No period given, so the chart lands on defaultPeriodForInterval(interval)
            chart.changeInterval(interval);
        };
        toolbar.appendChild(button);
        return button;
    });

    // Shows the interval and period on screen
    const status = document.createElement("span");
    Object.assign(status.style, statusStyle);
    toolbar.appendChild(status);

    const updateToolbar = (loading: boolean) => {
        buttons.forEach((button, i) => {
            Object.assign(button.style, buttonStyle(intervals[i] === currentInterval));
            button.disabled = loading;
        });
        status.textContent = loading ? "Loading…" : `Interval ${currentInterval}, period ${chart.currentPeriod}`;
    };
    updateToolbar(false);

    // dataLoadStarted: raised when an interval change starts loading. Disable the buttons meanwhile
    chart.dataLoadStarted.subscribe(() => updateToolbar(true));

    // dataRenderComplete: raised when the new candles are drawn. args.type is "interval-change" here
    chart.dataRenderComplete.subscribe((args) => {
        if (args.type === "interval-change") {
            updateToolbar(false);
        }
    });

    return financeChartPanel; // call financeChartPanel.cleanup() when the page goes away
}

// The toolbar uses SciTrader's UI colours: its --st-ui-* CSS variables, with the stylesheet's defaults
const toolbarStyle: Partial<CSSStyleDeclaration> = {
    display: "flex",
    flexWrap: "wrap",
    alignItems: "center",
    gap: "8px",
    padding: "8px",
    background: "var(--st-ui-background, #2b2839)",
    borderBottom: "1px solid var(--st-ui-divider, rgba(255,255,255,0.1))",
};

const buttonStyle = (active: boolean): Partial<CSSStyleDeclaration> => ({
    padding: "6px 14px",
    fontSize: "14px",
    fontFamily: "var(--st-font-family, sans-serif)",
    color: "var(--st-ui-text, #ffffff)",
    background: active ? "var(--st-ui-accent, #7464ff)" : "var(--st-ui-surface, #373447)",
    border: "1px solid var(--st-ui-divider, rgba(255,255,255,0.1))",
    borderRadius: "4px",
    cursor: "pointer",
});

const statusStyle: Partial<CSSStyleDeclaration> = {
    marginLeft: "8px",
    fontSize: "14px",
    fontFamily: "var(--st-font-family, sans-serif)",
    color: "var(--st-ui-text-muted, #9da2bc)",
};

createChart();

For an interval picker alongside symbol and period controls, in plain TypeScript and React, see the examples on Symbols, Intervals and Periods.

See also

• Changing the symbol
• Periods
• Toolbar controls