Skip to main content
Version: Next

Interface: ISeriesApi<TSeriesType, HorzScaleItem, TData, TOptions, TPartialOptions>

Represents the interface for interacting with series.

Type parameters

NameType
TSeriesTypeextends SeriesType
HorzScaleItemTime
TDataSeriesDataItemTypeMap<HorzScaleItem>[TSeriesType]
TOptionsSeriesOptionsMap[TSeriesType]
TPartialOptionsSeriesPartialOptionsMap[TSeriesType]

Methods

priceFormatter

priceFormatter(): IPriceFormatter

Returns current price formatter

Returns

IPriceFormatter

Interface to the price formatter object that can be used to format prices in the same way as the chart does


priceToCoordinate

priceToCoordinate(price): Coordinate

Converts specified series price to pixel coordinate according to the series price scale

Parameters

NameTypeDescription
pricenumberInput price to be converted

Returns

Coordinate

Pixel coordinate of the price level on the chart


coordinateToPrice

coordinateToPrice(coordinate): BarPrice

Converts specified coordinate to price value according to the series price scale

Parameters

NameTypeDescription
coordinatenumberInput coordinate to be converted

Returns

BarPrice

Price value of the coordinate on the chart


barsInLogicalRange

barsInLogicalRange(range): BarsInfo<HorzScaleItem>

Returns bars information for the series in the provided logical range or null, if no series data has been found in the requested range. This method can be used, for instance, to implement downloading historical data while scrolling to prevent a user from seeing empty space.

Example

Getting bars info for current visible range

const barsInfo = series.barsInLogicalRange(chart.timeScale().getVisibleLogicalRange());
console.log(barsInfo);

Example

Implementing downloading historical data while scrolling

function onVisibleLogicalRangeChanged(newVisibleLogicalRange) {
const barsInfo = series.barsInLogicalRange(newVisibleLogicalRange);
// if there less than 50 bars to the left of the visible area
if (barsInfo !== null && barsInfo.barsBefore < 50) {
// try to load additional historical data and prepend it to the series data
}
}

chart.timeScale().subscribeVisibleLogicalRangeChange(onVisibleLogicalRangeChanged);

Parameters

NameTypeDescription
rangeRange<number>The logical range to retrieve info for.

Returns

BarsInfo<HorzScaleItem>

The bars info for the given logical range.


applyOptions

applyOptions(options): void

Applies new options to the existing series You can set options initially when you create series or use the applyOptions method of the series to change the existing options. Note that you can only pass options you want to change.

Parameters

NameTypeDescription
optionsTPartialOptionsAny subset of options.

Returns

void


options

options(): Readonly<TOptions>

Returns currently applied options

Returns

Readonly<TOptions>

Full set of currently applied options, including defaults


priceScale

priceScale(): IPriceScaleApi

Returns interface of the price scale the series is currently attached

Returns

IPriceScaleApi

IPriceScaleApi object to control the price scale


setData

setData(data): void

Sets or replaces series data.

Example

Setting data to a line series

lineSeries.setData([
{ time: '2018-12-12', value: 24.11 },
{ time: '2018-12-13', value: 31.74 },
]);

Example

Setting data to a bars (or candlestick) series

barSeries.setData([
{ time: '2018-12-19', open: 141.77, high: 170.39, low: 120.25, close: 145.72 },
{ time: '2018-12-20', open: 145.72, high: 147.99, low: 100.11, close: 108.19 },
]);

Parameters

NameTypeDescription
dataTData[]Ordered (earlier time point goes first) array of data items. Old data is fully replaced with the new one.

Returns

void


update

update(bar): void

Adds new data item to the existing set (or updates the latest item if times of the passed/latest items are equal).

Example

Updating line series data

lineSeries.update({
time: '2018-12-12',
value: 24.11,
});

Example

Updating bar (or candlestick) series data

barSeries.update({
time: '2018-12-19',
open: 141.77,
high: 170.39,
low: 120.25,
close: 145.72,
});

Parameters

NameTypeDescription
barTDataA single data item to be added. Time of the new item must be greater or equal to the latest existing time point. If the new item's time is equal to the last existing item's time, then the existing item is replaced with the new one.

Returns

void


dataByIndex

dataByIndex(logicalIndex, mismatchDirection?): TData

Returns a bar data by provided logical index.

Example

const originalData = series.dataByIndex(10, LightweightCharts.MismatchDirection.NearestLeft);

Parameters

NameTypeDescription
logicalIndexnumberLogical index
mismatchDirection?MismatchDirectionSearch direction if no data found at provided logical index.

Returns

TData

Original data item provided via setData or update methods.


data

data(): readonly TData[]

Returns all the bar data for the series.

Example

const originalData = series.data();

Returns

readonly TData[]

Original data items provided via setData or update methods.


subscribeDataChanged

subscribeDataChanged(handler): void

Subscribe to the data changed event. This event is fired whenever the update or setData method is evoked on the series.

Example

function myHandler() {
const data = series.data();
console.log(`The data has changed. New Data length: ${data.length}`);
}

series.subscribeDataChanged(myHandler);

Parameters

NameTypeDescription
handlerDataChangedHandlerHandler to be called on a data changed event.

Returns

void


unsubscribeDataChanged

unsubscribeDataChanged(handler): void

Unsubscribe a handler that was previously subscribed using subscribeDataChanged.

Example

chart.unsubscribeDataChanged(myHandler);

Parameters

NameTypeDescription
handlerDataChangedHandlerPreviously subscribed handler

Returns

void


setMarkers

setMarkers(data): void

Allows to set/replace all existing series markers with new ones.

Example

series.setMarkers([
{
time: '2019-04-09',
position: 'aboveBar',
color: 'black',
shape: 'arrowDown',
},
{
time: '2019-05-31',
position: 'belowBar',
color: 'red',
shape: 'arrowUp',
id: 'id3',
},
{
time: '2019-05-31',
position: 'belowBar',
color: 'orange',
shape: 'arrowUp',
id: 'id4',
text: 'example',
size: 2,
},
]);

chart.subscribeCrosshairMove(param => {
console.log(param.hoveredObjectId);
});

chart.subscribeClick(param => {
console.log(param.hoveredObjectId);
});

Parameters

NameTypeDescription
dataSeriesMarker<HorzScaleItem>[]An array of series markers. This array should be sorted by time. Several markers with same time are allowed.

Returns

void


markers

markers(): SeriesMarker<HorzScaleItem>[]

Returns an array of series markers.

Returns

SeriesMarker<HorzScaleItem>[]


createPriceLine

createPriceLine(options): IPriceLine

Creates a new price line

Example

const priceLine = series.createPriceLine({
price: 80.0,
color: 'green',
lineWidth: 2,
lineStyle: LightweightCharts.LineStyle.Dotted,
axisLabelVisible: true,
title: 'P/L 500',
});

Parameters

NameTypeDescription
optionsCreatePriceLineOptionsAny subset of options, however price is required.

Returns

IPriceLine


removePriceLine

removePriceLine(line): void

Removes the price line that was created before.

Example

const priceLine = series.createPriceLine({ price: 80.0 });
series.removePriceLine(priceLine);

Parameters

NameTypeDescription
lineIPriceLineA line to remove.

Returns

void


seriesType

seriesType(): TSeriesType

Return current series type.

Example

const lineSeries = chart.addLineSeries();
console.log(lineSeries.seriesType()); // "Line"

const candlestickSeries = chart.addCandlestickSeries();
console.log(candlestickSeries.seriesType()); // "Candlestick"

Returns

TSeriesType

Type of the series.


attachPrimitive

attachPrimitive(primitive): void

Attaches additional drawing primitive to the series

Parameters

NameTypeDescription
primitiveISeriesPrimitive<HorzScaleItem>any implementation of ISeriesPrimitive interface

Returns

void


detachPrimitive

detachPrimitive(primitive): void

Detaches additional drawing primitive from the series

Parameters

NameTypeDescription
primitiveISeriesPrimitive<HorzScaleItem>implementation of ISeriesPrimitive interface attached before Does nothing if specified primitive was not attached

Returns

void