Trading Overlays (Price Lines)

Trading overlays are horizontal price lines for order, stop-loss, take-profit, and alert levels. They are drawn on the main chart as y-axis annotations and persist across zoom, theme change, chart-type switch, and streaming appends. Each line is a declarative config you own; ApexStock keeps the source of truth and re-applies it whenever the chart re-renders.

Adding lines

addPriceLine(config) is the generic form. addOrderLine, addStopLoss, addTakeProfit, and addAlert are typed shortcuts that preset the line's type (and, for order lines, color it from side). Each returns the line's id, or null if the config is invalid.

const entryId = apexStock.addOrderLine({ price: 98.5, side: 'buy', label: 'Entry' })
apexStock.addStopLoss({ price: 95 })
apexStock.addTakeProfit({ price: 104 })
apexStock.addAlert({ price: 100, onCross: (e) => notify(e.direction) })

Config reference

Only price is required.

Field	Type	Description
price	number	Required. The y level the line sits at.
id	string	Stable id; auto-generated ("tl-N") when omitted.
type	'order' | 'stop-loss' | 'take-profit' | 'alert'	Line kind. Preset by the shortcut methods.
side	'buy' | 'sell'	For order lines; drives the default color.
label	string	Defaults to a type/side/price summary.
color	string	Border + label color; defaults from the theme.
textColor	string	Label text color; defaults to white.
strokeDashArray	number	Dash length; default varies by type.
width	number	Line width.
labelPosition	'left' | 'right'	Which side the label sits on.
draggable	boolean	Allow drag-to-reprice; fires onMove on drop.
closable	boolean	Show a ✕ affordance; clicking it removes the line and fires onRemove.
onCross	function	Fired when a closed bar crosses the line.
onMove	function	Fired after a drag completes.
onRemove	function	Fired when removed via the close affordance.
meta	any	Arbitrary payload, returned by getPriceLine/getPriceLines.

Line colors default from the theme's trading-overlay palette and are re-read on every re-apply, so a theme switch recolors them automatically.

Interactivity

Both interactive behaviors are opt-in per line.

Draggable lines

apexStock.addStopLoss({
  price: 95,
  draggable: true,
  onMove: ({ id, price }) => {
    console.log(`Stop-loss ${id} moved to ${price}`)
  },
})

Dragging repositions the line live; onMove fires once, on drop.

Closable lines

apexStock.addTakeProfit({
  price: 104,
  closable: true,
  onRemove: ({ id }) => console.log(`Removed ${id}`),
})

Crossing alerts

onCross is edge-triggered: it fires when a newly-closed bar (from appendData) crosses the line relative to the previous bar's close. The callback receives { id, type, price, direction, bar }:

apexStock.addAlert({
  price: 100,
  onCross: ({ direction, price }) => {
    // direction reflects which way the close moved through the line
    notify(`Price crossed ${price} (${direction})`)
  },
})

Updating and removing

// Reprice or relabel an existing line
apexStock.updatePriceLine(entryId, { price: 97 })

// Remove one line by id
apexStock.removePriceLine(entryId)

// Remove every line
apexStock.clearPriceLines()

updatePriceLine and removePriceLine return false if no line with that id exists. An auto-generated label tracks the new price/type/side on update; a custom label is preserved unless you pass a new one.

Reading lines back

const line = apexStock.getPriceLine(entryId) // a copy of one line's config, or null
const all = apexStock.getPriceLines()        // copies of every line's config

Both return copies (with any meta you attached), so mutating the result does not affect the live overlays.