Kumo Charts

Alerts

The alerts module watches the price, an indicator or a drawing, and emits alertTrigger when a condition is met. An alert at a fixed level shows as a line on the chart that users can drag.

Show codeHide code
import { createChart } from '@kumo-charts/core';
import { alerts } from '@kumo-charts/core/alerts';
import { loadBars } from '@docs/data';

const chart = createChart(document.getElementById('chart')!, { modules: [alerts()] });

chart.data.set(await loadBars(), { interval: '1m' });
chart.data.setTimeframe('15m');

const last = chart.data.last()!;
chart.alerts.add({ id: 'above', trigger: 'cross-up', value: last.close * 1.01, label: 'Breakout' });
chart.alerts.add({
  id: 'below',
  trigger: 'cross-down',
  value: last.close * 0.99,
  label: 'Breakdown'
});

Adding

chart.alerts.add({
  id: 'btc-100k', // your id of the alert; the chart numbers one without it
  trigger: 'cross-up', // the condition
  value: 100000, // the level
  frequency: 'once', // how often it fires
  label: '100k' // the text on its line
});

The id is usually the alert's id in your application or on your server; without one the chart numbers it, alert-1 on. add() returns the alert's id.

chart.alerts.update('btc-100k', { value: 105000 });
chart.alerts.remove('btc-100k');
chart.alerts.set(alertsFromServer); // replaces every alert
chart.alerts.clear(); // removes every alert
chart.alerts.list();
chart.alerts.get('btc-100k'); // with its status: 'active', 'triggered' or 'disabled'

Conditions

trigger Fires when the value
cross-up crosses up through the other
cross-down crosses down through the other
cross crosses it either way
above is above it
below is below it
enter-channel enters the channel
exit-channel leaves the channel
inside-channel is inside the channel
outside-channel is outside the channel

Crossing, entering and leaving compare with the evaluation before: below then, above now, is a crossing; outside the channel (or on a bound) then, inside now, is entering it, and leaving is the other way round. Leaping from one side of the channel to the other, such as from 95 to 115 over a channel from 100 to 110, neither enters nor leaves it. Above, below, inside and outside look at the evaluation alone.

What to watch

source is the watched value, the main series' close by default. It can be:

const sources: ValueSource[] = [
  { kind: 'price', field: 'high' }, // a price of the main series
  { kind: 'indicator', id: maId, key: 'ma20' }, // a line of an indicator; without key, its first
  { kind: 'drawing', id: lineId }, // a drawing, where it is at each bar; without level, its first line
  { kind: 'series', id: ethId } // an added series
];

value is what it is compared with: a fixed level, another value, or the two bounds of a channel:

// The price crosses up through a trend line
chart.alerts.add({ id: 'a', trigger: 'cross-up', value: { kind: 'drawing', id: trendLineId } });

// MACD crosses up through its signal line
chart.alerts.add({
  id: 'b',
  source: { kind: 'indicator', id: macdId, key: 'macd' },
  trigger: 'cross-up',
  value: { kind: 'indicator', id: macdId, key: 'signalLine' }
});

// The price leaves a rectangle
chart.alerts.add({
  id: 'c',
  trigger: 'exit-channel',
  value: [
    { kind: 'drawing', id: rectId, level: 'top' },
    { kind: 'drawing', id: rectId, level: 'bottom' }
  ]
});

Watching indicators needs the indicators module, watching drawings the drawings module. chart.drawings.levels(id) lists the lines of a drawing that can be watched. An indicator or a drawing an alert watches cannot be removed before the alert: the error names the alerts that use it.

How often

frequency Meaning
once (default) Fires once, then its status is triggered until rearm()
once-per-bar At most once a bar, on the update that meets the condition
once-per-bar-close Closes only: each bar is evaluated when the next one starts
every-time On every update that meets the condition
chart.alerts.rearm('btc-100k');
chart.alerts.update('btc-100k', { enabled: false }); // paused

When it fires

chart.on('alertTrigger', ({ id, time, value, threshold, replay }) => {
  if (replay) return; // fired while replaying history: usually nothing to notify
  notify(`${id}: ${value} crossed ${threshold}`);
});

time is the bar that met the condition, value the watched value, threshold the level at that bar (for channels, the bound it went through).

Dragging on the chart

An alert at a fixed level shows as a line users can drag. Dragging emits alertDrag; the alert follows, and keeps the level where the user lets go:

chart.on('alertDrag', ({ id, phase, price }) => {
  if (phase === 'end') saveAlert(id, { value: price });
});

How the line looks:

chart.alerts.add({
  id: 'x',
  trigger: 'cross',
  value: 98000,
  color: '#e3a33b', // the theme's alert color by default
  lineStyle: 'dashed',
  draggable: true, // whether it can be dragged
  visible: true, // whether its line shows
  buttons: [{ id: 'remove', text: '✕' }] // buttons on its label; a click emits buttonClick
});

chart.on('buttonClick', ({ kind, id, buttonId }) => {
  if (kind === 'alert' && buttonId === 'remove') chart.alerts.remove(id);
});

Alerts while the page is closed

Alerts on the chart work while the page is open. To watch them on a server, use createAlertEngine() of @kumo-charts/core/alert-engine: it draws nothing, but builds the timeframe from the bars, computes the indicators and where the lines of drawings are at each bar, and evaluates the alerts as a chart does, so that on the same bars, indicators and drawings it fires exactly what a chart fires. It runs in Node.js.

import { createAlertEngine } from '@kumo-charts/core/alert-engine';
import { trendLine } from '@kumo-charts/core/drawings';
import { RSI } from '@kumo-charts/core/indicators';

const engine = createAlertEngine({ indicators: [RSI], drawings: [trendLine] });

engine.data.set(bars, { interval: '1m' }); // bars of the source interval
engine.data.setTimeframe('15m'); // the alerts are evaluated on bars of 15 minutes
engine.indicators.add({ id: 'rsi', type: 'RSI' });
engine.drawings.add({
  id: 'support',
  type: 'trend-line',
  points: [
    { time: '2026-05-01T08:00:00Z', price: 94200 },
    { time: '2026-05-03T16:00:00Z', price: 96800 }
  ]
});
engine.alerts.set([
  { id: 'rsi-70', source: { kind: 'indicator', id: 'rsi' }, trigger: 'cross-up', value: 70 },
  {
    id: 'support',
    trigger: 'cross-down',
    value: { kind: 'drawing', id: 'support' },
    frequency: 'once-per-bar-close'
  }
]);

engine.on('alertTrigger', (event) => {
  notify(`${event.id}: ${String(event.value)}`);
});
onTrade((trade) => engine.data.addTrades(trade)); // the live trades, as they come

Its data, indicators, drawings and alerts work as a chart's, without what only drawing needs (panes, colors, dragging). The indicator and drawing types go to createAlertEngine(), as to the modules of a chart; the trading calendar is its calendar option, as the chart's calendar option, and setCalendar() changes it. An indicator needs enough bars for its first value: data.prepend() adds older ones, and indicators.valuesAt() reads its values at a bar.

↑↓ to select · Enter to open · Esc to close