Skip to main content
Version: Next

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

Represents the interface for interacting with series.

Type parameters​

• TSeriesType extends SeriesType

• HorzScaleItem = Time

• TData = SeriesDataItemTypeMap<HorzScaleItem>[TSeriesType]

• TOptions = SeriesOptionsMap[TSeriesType]

• TPartialOptions = SeriesPartialOptionsMap[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​

• price: number

Input 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​

• coordinate: number

Input 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.

Parameters​

• range: IRange<number>

The logical range to retrieve info for.

Returns​

BarsInfo<HorzScaleItem>

The bars info for the given logical range.

Examples​

const barsInfo = series.barsInLogicalRange(chart.timeScale().getVisibleLogicalRange());
console.log(barsInfo);
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);

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​

• options: TPartialOptions

Any 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.

Parameters​

• data: TData[]

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

Returns​

void

Examples​

lineSeries.setData([
    { time: '2018-12-12', value: 24.11 },
    { time: '2018-12-13', value: 31.74 },
]);
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 },
]);

update()​

update(bar, historicalUpdate?): void

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

Parameters​

• bar: TData

A 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.

• historicalUpdate?: boolean

If true, allows updating an existing data point that is not the latest bar. Default is false. Updating older data using historicalUpdate will be slower than updating the most recent data point.

Returns​

void

Examples​

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

dataByIndex()​

dataByIndex(logicalIndex, mismatchDirection?): TData

Returns a bar data by provided logical index.

Parameters​

• logicalIndex: number

Logical index

• mismatchDirection?: MismatchDirection

Search direction if no data found at provided logical index.

Returns​

TData

Original data item provided via setData or update methods.

Example​

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

data()​

data(): readonly TData[]

Returns all the bar data for the series.

Returns​

readonly TData[]

Original data items provided via setData or update methods.

Example​

const originalData = series.data();

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.

Parameters​

• handler: DataChangedHandler

Handler to be called on a data changed event.

Returns​

void

Example​

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

series.subscribeDataChanged(myHandler);

unsubscribeDataChanged()​

unsubscribeDataChanged(handler): void

Unsubscribe a handler that was previously subscribed using subscribeDataChanged.

Parameters​

• handler: DataChangedHandler

Previously subscribed handler

Returns​

void

Example​

chart.unsubscribeDataChanged(myHandler);

createPriceLine()​

createPriceLine(options): IPriceLine

Creates a new price line

Parameters​

• options: CreatePriceLineOptions

Any subset of options, however price is required.

Returns​

IPriceLine

Example​

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

removePriceLine()​

removePriceLine(line): void

Removes the price line that was created before.

Parameters​

• line: IPriceLine

A line to remove.

Returns​

void

Example​

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

priceLines()​

priceLines(): IPriceLine[]

Returns an array of price lines.

Returns​

IPriceLine[]

seriesType()​

seriesType(): TSeriesType

Return current series type.

Returns​

TSeriesType

Type of the series.

Example​

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

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

attachPrimitive()​

attachPrimitive(primitive): void

Attaches additional drawing primitive to the series

Parameters​

• primitive: ISeriesPrimitive<HorzScaleItem>

any implementation of ISeriesPrimitive interface

Returns​

void

detachPrimitive()​

detachPrimitive(primitive): void

Detaches additional drawing primitive from the series

Parameters​

• primitive: ISeriesPrimitive<HorzScaleItem>

implementation of ISeriesPrimitive interface attached before Does nothing if specified primitive was not attached

Returns​

void

moveToPane()​

moveToPane(paneIndex): void

Move the series to another pane.

If the pane with the specified index does not exist, the pane will be created.

Parameters​

• paneIndex: number

The index of the pane. Should be a number between 0 and the total number of panes.

Returns​

void

getPane()​

getPane(): IPaneApi<HorzScaleItem>

Returns the pane to which the series is currently attached.

Returns​

IPaneApi<HorzScaleItem>

Pane API object to control the pane