v4.x -> v5.x

When upgrading, please reference each of the below LCJS entries in your application (for example, using Search functionality in your code base).

For each code block found this way, refer to the corresponding migration guide.

Licensing

Before v5.0.0, passing no license to lightningChart() method resulted in automated usage of so called "community licensing". This mode was intended for non-commercial use, such as hobby projects. However, many misunderstood this as the intended way to develop commercial projects (instead of using developer licenses).

Starting with v5.0.0, a license key is always required when running an application.

• For deployment scenarios, nothing is changed.
• Trial users: you now have to make sure you pass your personal trial key to lightningChart function in your chart application. For more information, see Trials
• Existing customers developers: you now have to make sure you pass your personal developer key to lightningChart function in your chart application. For more information, see Developer licenses

lightningChart() entry point instance management

Starting with LCJS v5.0.0, it's important to do only one call to the lightningChart() library entry point function. You should call this function once and create all of the charts from the same returned object.

const lc = lightningChart()

const chart1 = lc.ChartXY()
const chart2 = lc.PieChart()

Each call to this function will create a new shared WebGL context that can be used to create multiple charts with some shared resources to improve performance and to remove the 16 chart limit that came from browsers limiting the max WebGL instance count to 16.

React users: we suggest to use 1 shared context that manages the LightningChart object used within the whole app. See React for more information.

ZoomBandChart refactoring

The ZoomBandChart feature has been refactored with 2 main goals:

1. Better user experience - clearer user interactions and visual design.
2. Simpler and more understandable end user API.

Migration guide and breaking changes from old version:

End user API

Attaching series/axes

Before, ZBC was attached to 1 or more Axes when it is created. This couldn't be changed afterwards.

// Before
const zoomBandChart = Dashboard.createZoomBandChart({ axis: myAxisX, ... })

Now, each Series that should be displayed in ZBC is separately added with ZoomBandChart.add method. This allows dynamically adding and removing series from ZBC at any point in time.

// After
const zoomBandChart = Dashboard.createZoomBandChart({ ... })
const zbcSeries = zoomBandChart.add(mySeries)
zoomBandChart.disposeSeries(zbcSeries)

Styling ZBC series

Before, ZBC series were styled by passing a callback function which triggers for all series in the ZBC:

// Before
ZoomBandChart.setSeriesStyle((series, refSeries) => {
    if (refSeries === myLineSeries) {
        series.setStrokeStyle(...)
    }
})

Now, adding a series to ZBC returns a handle to the ZBC series, which you can style like the original series:

// After
ZoomBandChart.add(myLineSeries)
    .setStrokeStyle(...)

Other breaking changes

• ZoomBandChart now requires hosted file resources to fully work.
  • The draggable "Nib" pictures are image assets.
  • The assets are included in NPM package under dist/resources/zoomBandChart
  • See resourcesBaseUrl in API documentation for more information about LCJS resources.
• ZoomBandChart no longer ensures attached axes are aligned.
  • It only aligns itself to match the attached axes.
  • If user needs to align several axes with each other, use Axis.setThickness method.

New capabilities and other improvements

• ZoomBandChart can now be created outside a Dashboard with LightningChart.ZoomBandChart method.
• New feature, sharedValueAxis which can be used to display all ZBC series on the same value axis. This option has to be specified when ZoomBandChart is created.
• Improved built-in user interactions.
• ZBC series style is now automatically matched to look exactly as the original series. Before, series often looked different in ZBC.

OHLC Series rework

OHLC Series has been completely reworked with the main intention of improving performance. Loading time improved by ~40x and data capacity by ~200x (with average desktop GPU) - the difference is massive.

Many related old classes/interfaces were removed or renamed. Here are guides for migrating old applications to use the new feature. There are no large differences between the new and old features.

• Removed OHLCSeriesTypes and OHLCSeriesWithAutomaticPacking. If you were using OHLCSeriesTraditional you should replace the type with OHLCSeries, OHLCSeriesCandlesticks or OHLCSeriesBars.
• Selection between candles/bars changed from chart.addOHLCSeries({ positiveFigure: OHLCFigures.Candlestick }) to chart.addOHLCSeries({ type: OHLCSeriesTypes.Candlesticks }).
• Properties of OHLCSegment are now directly accessed via properties rather than methods. For example, OHLCSegment.getClose() -> OHLCSegment.close, etc. This relates to cursors, result table formatting and use of solve nearest.
• Styling API for OHLC Series has changed. See API documentation for OHLCSeries, OHLCSeriesCandlesticks and OHLCSeriesBars for commonly needed APIs.

Figure Series rework

All Figure Series (RectangleSeries, SegmentSeries, PolygonSeries, BoxSeries, EllipseSeries) have been reworked with the main intention of improving performance, enabling use cases that need large numbers of figures. New implementation is much more performance efficient, on average ~50x more powerful or even more.

For the most part the API is unchanged, but some classes have been removed to simplify the API and cope with the performance improvements:

• Removed BoxAndWhiskers
• Removed BoxFigureConstructor
• Removed CustomizableFigure
• Removed SimpleFigureSeries

Related features are still supported, these removed classes were simply extra complications.

solveNearestFromScreen

The parameter for solveNearestFromScreen methods were changed from { x: number, y: number } to { clientX: number, clientY: number }. The values of these numbers are not identical! Before x and y referred to internal LightningChart JS engine coordinates. This concept is now deprecated (users don't have to concern themselves with them). Now, clientX and clientY should be in the HTML coordinate system, which originates from top left corner of the web page and is measured in pixels.

// Before
ChartXY.onSeriesBackgroundMouseMove((_, event) => {
    const locationEngine = ChartXY.engine.clientLocation2Engine(event.clientX, event.clientY)
    const nearest = LineSeries.solveNearestFromScreen(locationEngine)
})

// After
ChartXY.onSeriesBackgroundMouseMove((_, event) => {
    const nearest = LineSeries.solveNearestFromScreen(event)
})

translatePoint, translatePoint3D

LightningChart JS involves a number of different coordinate systems. Previously users could translate coordinates between them using the functions translatePoint and translatePoint3D.

Using these methods was quite complicated, as the user had to do multiple operations to translate coordinates from client to axes, or vice versa. To improve on this, the old methods translatePoint, translatePoint3D are removed, and replaced with Chart.translateCoordinate method.

To see how this is used, please see Developer Documentation: https://lightningchart.com/js-charts/docs/advanced-topics/coordinate-translations/ The most important use cases have use snippets written in there.

Changes to Theme interface

The following new properties have been added to Theme interface. If you are not using built-in themes or latest version of lcjs-themes, then you need to define these new properties:

• uiTextFillStyleHidden - fill style of UI text when hidden via LegendBox.
• uiButtonFillStyleHidden - fill style of UI buttons when hidden via LegendBox.
• cursorPointMarkerSize - size of cursor point markers
• cursorPointMarkerShape - shape of cursor point markers
• chartMarkerPointMarkerSize - size of chart marker point markers
• chartMarkerPointMarkerShape - shape of chart marker point markers
• seriesMarkerPointMarkerFillStyle - fill style of series marker point markers
• seriesMarkerPointMarkerSize - size of series marker point markers
• seriesMarkerPointMarkerShape - shape of series marker point markers
• ohlcCandleThicknessPixels - ohlc candle body thickness
• ohlcCandleTailStrokeStylePositive - ohlc positive candle tail style
• ohlcCandleTailStrokeStyleNegative - ohlc negative candle tail style
• ohlcBarThicknessPixels - ohlc bar thickness
• barChartBackgroundFillStyle - bar chart background fill style
• barChartBackgroundStrokeStyle - bar chart background stroke style
• barChartTitleFont - bar chart title font
• barChartTitleFillStyle - bar chart title fill
• barChartSeriesBackgroundFillStyle - bar chart series background fill style
• barChartSeriesBackgroundStrokeStyle - bar chart series background stroke style
• barChartBarFillStyle - bar chart bar fill style
• barChartBarStrokeStyle - bar chart bar stroke style
• barChartValueAxisTitleFont - bar chart value axis title font
• barChartValueAxisTitleFillStyle - bar chart value axis title fill
• barChartValueAxisStrokeStyle - bar chart value axis stroke
• barChartValueAxisTicks - bar chart value ticks style
• barChartCategoryAxisTitleFont - bar chart category axis title font
• barChartCategoryAxisTitleFillStyle - bar chart category axis title fill
• barChartCategoryAxisStrokeStyle - bar chart category axis stroke
• barChartCategoryLabels - bar chart category labels style
• barChartValueLabelsAfterBars - bar chart value labels style after bars
• barChartValueLabelsInsideBars - bar chart value labels style inside bars
• polarHeatmapSeriesFillStyle - polar heatmap fill style
• zoomBandChartDefocusOverlayFillStyle - zoom band chart defocus overlay fill
• zoomBandChartSplitterStrokeStyle - zoom band chart splitter stroke
• zoomBandChartKnobFillStyle - zoom band chart knob fill style
• zoomBandChartKnobSize - zoom band chart knob size

Removed Theme properties:

• cursorPointMarkerStrokeStyle
• chartMarkerPointMarkerStrokeStyle
• ohlcCandleBodyStrokeStylePositive
• ohlcCandleBodyStrokeStyleNegative
• ohlcCandleStrokeStyle

PointMarker changes

API around Point Markers (found in cursors, chart markers and series markers) has been greatly simplified and improved.

Main changes:

• No more generics, just 1 type PointMarker which shows available API. Shape can be changed with PointMarker.setShape method. This also adds support for more shape options.
• Point Marker border is removed.
• Default look changed.

Removed APIs:

• PointMarkers
• EmptyPointMarker
• PointMarker.setStrokeStyle
  • Removed, no direct replacement
• CursorBuilder.setPointMarker
  • Previous use cases in changing shape can be replaced with PointMarker.setShape
  • Previous use cases in styling can be replaced with other methods of PointMarker

Previously default cursor PointMarker was not visible, now it is a small crosshair. To restore previous look you can either use

chart.setAutoCursor((cursor) => cursor.setPointMarkerVisible(false))

or

const chart = lightningChart().ChartXY({ theme: { ...Themes.darkGold, cursorPointMarkerFillStyle: emptyFill } })

VisibleTicks, isVisibleTicks

These have been removed. They can be directly replaced with:

• VisibleTicks -> TickStyle
• isVisibleTicks -> isTickStyle

Previous usage of isVisibleTicks can be removed in most cases, as all tick styles now have API for modifying tick style properties, unlike before when you had to ensure you were dealing with an instance of VisibleTicks.

pixelScale

pixelScale properties should be changed to coordsRelative.

// Before
const textBox = chart.addUIElement(UIElementBuilders.TextBox, chart.pixelScale)

// After
const textBox = chart.addUIElement(UIElementBuilders.TextBox, chart.coordsRelative)

CursorPoint

CursorPoint.series property name changed to owner and type to unknown.

UICheckBox, UIElementBuilders.CheckBox, LegendBox.setEntries

The styling of UI checkboxes has changed in two main ways:

1. More shapes of buttons have been added. All options in PointShape enumeration are now available.
2. Button border has been removed.

Changed APIs:

• setPictureOff, setPictureOn
  • Replace usage with setButtonShape
• setButtonOffStrokeStyle, setButtonOnStrokeStyle
  • No replacement available
• setButtonOnSize, setButtonOffSize
  • Replaced usage with setButtonSize

...as well as respective getter methods.

See LegendBoxAddOptions in API reference to learn how to apply different shapes to legend entries.

PieChartWithLabelsOnSides

Some minor style API changes:

• Removed setLabelConnectorGap
• Removed setLabelConnectorLength
• Added setLabelSliceOffset
• Added setLabelConnectorGapStart
• Added setLabelConnectorEndLength

The label placement basis has changed a bit, so if you were using the previous methods to tweak the label positioning, now you'll have to adapt to the new methods.

onHighlight methods parameters changed

To be symmetrical with other event APIs, the parameters to all onHighlight methods have changed slightly.

Before:

Component.onHighlight((highlight) => { ... })

After:

Component.onHighlight((component, highlight) => { ... })

CustomTick.onValueChange method parameters changed

To be symmetrical with other event APIs, the parameters to CustomTick.onValueChange method has changed slightly.

Before:

CustomTick.onValueChange((value) => { ... })

After:

CustomTick.onValueChange((customTick, value) => { ... })

MarkerBuilders.XY

This property is removed and use should be replaced with either MarkerBuilders.ChartMarkerXY or MarkerBuilders.SeriesMarkerXY.

The only difference between the available two options is default style.

SpiderChart.addSeries

The method signature of SpiderChart.addSeries method has changed. If you used the pointShape parameter please apply following migration:

Before:

SpiderChart.addSeries(PointShape.Circle)

After

SpiderChart.addSeries({ pointShape: PointShape.Circle })