useAlerts

Client-side price alerts. Draws a labelled locked horizontal line for each alert (a Y-axis price mark plus a bell-marked caption above the line) and polls the latest candle once per second, firing a callback when the price crosses the alert level. Crossing detection uses the previous (final) bar’s close as the baseline and counts the forming bar’s high/low as touching the level, so a wick that pierces the level and comes back between two ticks still fires. This is the primary hook for reacting to price events — e.g. forwarding a buy/sell signal to your backend or triggering a push notification.

Multi-instance safe

The alert list lives in the shared store (state.alerts) and the crossing poller is owned by the provider (one poller, active only while alerts exist). onAlertTriggered registers a listener and returns an unsubscribe function — multiple components (toolbar, status bar, sound trigger) can observe firings simultaneously; every registered listener is invoked on each crossing.

No overlay setup needed

The alertLine overlay template the hook draws with is registered automatically (by registerExtensions() and lazily inside useAlerts) — you don’t need to pass it through the provider’s overlays prop.

import { useAlerts } from "react-klinecharts-ui";

const { alerts, addAlert, removeAlert, clearAlerts, onAlertTriggered } =
  useAlerts();

// Default: orange dashed line, bell + price/message caption.
const id = addAlert(65000, "crossing_up", "BTC broke 65k");

// Customize the look via the optional 4th argument (AlertLineExtendData).
addAlert(70000, "crossing_up", "Take profit", {
  color: "#e91e63",
  showBell: true,
});

// Indicator-value alert (e.g. RSI crossing 70). The 5th argument targets a
// specific indicator figure series instead of the main symbol's price.
addAlert(70, "crossing_up", "RSI overbought", undefined, {
  type: "indicator",
  indicatorId: "sub_RSI_TV",
  figureKey: "rsi",
});

// onAlertTriggered returns an unsubscribe; register as many as you need.
const off = onAlertTriggered((alert) => {
  console.log("Alert fired:", alert.message, alert.price);
});
// later: off();

Try it

API

Property	Type	Description
alerts	Alert[]	Current alerts (active and triggered)
addAlert	(price, condition, message?, extendData?, target?) => string	Create an alert; returns its id (returns "" and creates nothing for a non-finite price). extendData (AlertLineExtendData) customizes the line/label. target (AlertTarget) watches a price level (default) or an indicator figure value
removeAlert	(id: string) => void	Remove a single alert and its line
clearAlerts	() => void	Remove all alerts
onAlertTriggered	(cb: (alert: Alert) => void) => () => void	Register a firing listener; returns an unsubscribe. Multiple listeners are all invoked

type AlertCondition = "crossing_up" | "crossing_down" | "crossing";

interface Alert {
  id: string;
  price: number;
  condition: AlertCondition;
  message?: string;
  triggered: boolean;
  /** Line/label style; persisted so it survives undo/redo & layout presets. */
  extendData?: AlertLineExtendData;
}

interface AlertLineExtendData {
  /** Line / mark bg / label color. Default: "#ff9800" */
  color?: string;
  /** Caption text. Defaults to `message ?? formatted price` (symbol precision). */
  text?: string;
  /** Line style overrides (shared with orderLine). */
  line?: OrderLineLineStyle;
  /** Y-axis price mark style overrides. */
  mark?: OrderLineMarkStyle;
  /** Caption text style overrides. */
  label?: OrderLineLabelStyle;
  /** Show a 🔔 marker before the caption. Default: true */
  showBell?: boolean;
}

Condition	Fires when
crossing_up	Previous (final) bar close < price and (current close >= price or forming bar high >= price)
crossing_down	Previous (final) bar close > price and (current close <= price or forming bar low <= price)
crossing	Either direction

Fires once

Detection is polled every second from chart.getDataList(). An alert fires at most once (its triggered flag flips to true); recreate it to re-arm.

See the Backend signals guide for wiring alerts to a server or notifications.