Timeframes and calendars
Give the chart 1-minute bars and it builds 5-minute, 4-hour, daily, weekly or other bars in the browser, so switching timeframes needs nothing more from your server. It builds them by a trading calendar: when a day starts, which sessions it trades, which days are trading days.
Intervals
A number and a unit:
| Unit | Meaning | Examples |
|---|---|---|
s |
second | '15s' |
m |
minute | '1m', '5m' |
h |
hour | '1h', '4h' |
D |
day | '1D' |
W |
week | '1W' |
M |
month | '1M', '3M' |
Only minutes m and months M differ by case; other units take either ('4H', '1d'). A count of 1 can be left out: 'D' is '1D'. An object works too: { unit: 'hour', count: 4 }.
Switching timeframes
Show codeHide code
import { createChart } from '@kumo-charts/core';
import { loadBars } from '@docs/data';
const chart = createChart(document.getElementById('chart')!);
chart.data.set(await loadBars(), { interval: '1m' });
chart.data.setTimeframe('4h');The interval given to set() is the source interval; setTimeframe() sets the displayed one, and setTimeframe(null) shows the source bars again:
chart.data.sourceInterval(); // { unit: 'minute', count: 1 }
chart.data.timeframe(); // { unit: 'hour', count: 4 }, or null at the source intervalA built bar starts at the start of its period, opens at its first bar's open, has the highest high and the lowest low of its bars, closes at the last bar's close, and sums their volume. The latest one updates with the real-time data.
Bars of several days (such as '2D') count trading days: each takes exactly that many trading days in a row (the calendar's weekdays), the days without trading left out, and is dated at the first of them. They are grouped in turn from 1 January 1970, so the same calendar always makes the same groups.
Indicators can be computed in a timeframe longer than the chart's too, such as an hourly average on 5-minute bars; see Indicators.
Which timeframes can be built
- Seconds, minutes and hours: multiples of the source interval. 1-minute bars build 3-minute and hourly bars, not 90-second ones.
- Days: from an interval that divides a day, such as 1 minute, 15 minutes or 4 hours, not 7 minutes.
- Weeks and months: from an interval that divides a day, or from 1 day; not from 2 days.
- Never shorter than the source.
setTimeframe() throws for a timeframe it cannot build, saying why. For a menu of timeframes, canBuildTimeframe() tells which can be chosen:
import { canBuildTimeframe } from '@kumo-charts/core';
canBuildTimeframe('4h', '1h'); // true
canBuildTimeframe('1W', '2D'); // falseIntervals of seconds, minutes and hours have a fixed length, which intervalDuration() gives in milliseconds; days, weeks and months last as the trading calendar says, and give null:
import { intervalDuration } from '@kumo-charts/core';
intervalDuration('15m'); // 900000
intervalDuration('1D'); // nullTime zones
Two options take a time zone:
timeZone: the zone the axis and the crosshair show times in; the user's local zone unless set.calendar.timeZone: the zone the bars' days and weeks are cut in, and where hours start;UTCby default.
Crypto exchanges cut their bars in UTC, with days starting at 00:00 UTC: the default fits them, and times still show in the user's zone. Stocks, futures and other bars given in an exchange's time need the exchange's zone:
createChart(container, {
timeZone: 'Asia/Shanghai', // times shown in Shanghai time
calendar: { timeZone: 'America/New_York' } // US stocks: days start at midnight in New York
});The calendar must fit the data. Bars of minutes and hours must start where the calendar starts one: hours starting on the hour in UTC, given to a calendar in India's time, half an hour apart, make set() throw and say what to set, rather than move the bars to other times. Bars of days, weeks and months go by their trading date, dated at midnight, at the open or at the close alike.
Time zones are IANA names, such as Asia/Shanghai, America/New_York or UTC.
Trading sessions
Markets that trade around the clock need nothing. For markets with trading hours, describe them in calendar:
| Option | Meaning | Default |
|---|---|---|
sessions |
The sessions of a trading day as 'HH:MM-HH:MM'; an end before its start crosses midnight. Times outside every session are dropped |
[] (all day) |
dayStart |
When a trading day starts; from this time on, times belong to the next trading day | '00:00' |
weekdays |
The days that are trading days, 0 being Sunday | every day |
weekStart |
The first day of a week bar, 0 being Sunday | 1 (Monday) |
Some examples:
// Shanghai stocks: a morning and an afternoon session, Monday to Friday
createChart(container, {
calendar: {
timeZone: 'Asia/Shanghai',
sessions: ['09:30-11:30', '13:00-15:00'],
weekdays: [1, 2, 3, 4, 5]
}
});
// Chinese futures with a night session: the session from 21:00 belongs to the next trading day,
// Friday night's to Monday
createChart(container, {
calendar: {
timeZone: 'Asia/Shanghai',
sessions: ['21:00-02:30', '09:00-10:15', '10:30-11:30', '13:30-15:00'],
dayStart: '21:00',
weekdays: [1, 2, 3, 4, 5]
}
});
// Forex: the day changes at 17:00 New York time
createChart(container, {
calendar: {
timeZone: 'America/New_York',
dayStart: '17:00',
weekdays: [1, 2, 3, 4, 5]
}
});With sessions, hours count from the start of each session: Shanghai's hourly bars start at 9:30, 10:30, 13:00 and 14:00.
Holidays and other rules
For what fixed rules cannot say, such as holidays or an early close, calendar.bucket decides which bar each time goes to:
const holidays = new Set(['2026-10-01', '2026-10-02']);
createChart(container, {
calendar: {
timeZone: 'Asia/Shanghai',
sessions: ['09:30-11:30', '13:00-15:00'],
bucket: (time, interval, fallback) => {
const date = new Date(time + 8 * 3_600_000).toISOString().slice(0, 10);
return holidays.has(date) ? null : fallback(time);
}
}
});Return the start of the bar, or null to drop the time. fallback is what the other calendar options give. The returned starts must not go back in time.
The calendar in your own code
When your code needs to line times up as the chart does, for example to build bars on a server or to tell which bar a time belongs to, use createCalendar():
import { createCalendar } from '@kumo-charts/core';
const calendar = createCalendar({
timeZone: 'Asia/Shanghai',
sessions: ['09:30-11:30', '13:00-15:00']
});
calendar.bucket('2026-05-06T02:15:00Z', '1h'); // 10:15 in Shanghai falls in the bar from 9:30: its startIt needs no chart and runs in Node.js too.
With a chart, chart.data.calendar() is the calendar the chart uses (its calendar option, in the chart's time zone), for example to group bars by trading day in a plugin. It is a new one once the options change, so read it when you need it.