A high-performance charting library for JavaScript and TypeScript.
Points of interest:
If you prefer to setup your own project, there are two main ways to get LightningChart.js in your JavaScript or TypeScript project:
Install the library package from NPM.
npm install --save @arction/lcjs
This package can be used with any bundler that supports CommonJS. Some examples of bundlers that work are WebPack, Parcel and Rollup.
Check our getting started video on LightningChart JS to see this in action.
Any of our Examples can be used as a seed project. All examples on that page have been made to standalone repositories which can be found on our GitGub. Standalone Example Repositories
The library is distributed with a browser ready IIFE bundle. This bundle can be used directly in browsers with script tag. You can see an example implementation of this method on our GitHub. LightningChart JS html usage example.
All of our examples can be used in the html page. To use them,
first find an example you want to use from interactive examples.
Click Edit this example. On the bottom of the page click on the button that reads CJS. That will switch our code to be IIFE compatible.
After that, the code can be copied to the html page. See our LightningChart JS html usage example for more detailed information.
When the library is used without a license, it will run with a LightningChart JS logo on the chart. The logo is a link to the LightningChart JS product page.
There is a small performance drop when the chart is running without a license key compared to running with a valid license.
A development license is required for development in a commercial environment. The license is verified with a license server. Internet connection is required for license verification. Each developer requires own development license. See "Using a license" for how to use the development license. When using a development key, the chart will just like it will in production.
A deployment license is required for commercial use. The deployment license is provided the same way as a development license. See "Using a license" for how to use the deployment license.
When using a deployment license, the chart will render without the LightningChart JS logo. The deployment license supports a "Deployment Test" domain. If the domain that the library is currently running in matches the deployment test domain specified with the deployment license, the chart will render with a "Deployment Test" text on top of the chart. This domain is meant to support using a staging environment and having the ability to switch to the production version without changing the license.
An application deployment license is required for deploying any application on other platforms than the web. See "Using a license" for how to use the application deployment license.
When using an application deployment license, the chart will render without the LightningChart JS logo.
To use your LightningChart JS license, you must supply license information when lightningChart is initiated:
// Create an instance of LightningChart for creation of charts.
// ----- Licensed version -----
const lc = lightningChart({
license: 'my-license-number'
})...where my-license-number should be replaced with either a development license for development or a deployment license for deployment.
See LightningChartOptions for detailed information.
To use your LightningChart JS Application deployment license, you must also supply extra license information.
// Create an instance of LightningChart for creation of charts.
// ----- Application Deployment licensed version -----
const lc = lightningChart({
license: 'my-license-number'
licenseInformation: licenseInformationObject
})...where licenseInformationObject is an object that implements AppDeploymentLicenseInformation interface.
See LightningChartOptions for detailed information.
Different purchasing options can be found on our website.
Usage of LCJS starts by importing and initiating the lightningChart reference.
const { lightningChart } = require('@arction/lcjs')
const lightningChart = lightningChart({
// If you have a license, supply it here. Otherwise, the arguments can be left blank, which results in automatically using Community License.
license: 'my-license-number'
})For more information about using a license, see "Using a license".
Immediately afterwards, you can create any chart or dashboard component, by methods of LightningChart. In this short example, we'll look into creating a basic xy line chart. To learn about all the available chart types, see LightningChart.
// Create a XY chart.
const chartXY = lightningChart.ChartXY()The usage of all LCJS charts follows a roughly centralized idea, where the chart is the primary framework that defines the component in the web document. The data visualization is then controlled with components of the chart - the most common type being series.
// Add series for visualizing a set of XY coordinates as a continuous line.
const lineSeries = chartXY.addLineSeries()The term "series" has quite a loose definition, but it always involves a data set which is supplied by the user, and some method of visualizing the data, that depends on the type of series. ChartXY, for example, supports a large collection of different series types, which can be combined to create different data visualizations. For the full list, see ChartXY.
// Finish the line chart visualization by pushing a set of XY coordinates to the series.
lineSeries.add([
{ x: 0, y: 0 },
{ x: 20, y: 0 },
{ x: 45, y: -47 },
{ x: 53, y: 335 },
{ x: 57, y: 26 },
{ x: 62, y: 387 },
{ x: 74, y: 104 },
{ x: 89, y: 0 },
{ x: 95, y: 100 },
{ x: 100, y: 0 },
])This was a quick overview on the general usage of LCJS. The most convenient way to learn of the available features is our official Interactive Examples.
The intended design of LCJS API documentation is a chain of links that guide you from the top level to the feature you require information about.
Let's look at a practical example;
Say you're developing a proof of concept application with ChartXY and LineSeries. When pointing at the chart with mouse, you notice the cursor that automatically pops up and displays the closest data point to the mouse location. Now, instead of "X: 524", you'd like it to show, for example: "Sample #524".
In this case, you can be pretty sure that the cursor is a property of either LineSeries, or ChartXY. You can find these items in the API documentation by text search (Ctrl+F "lineSeries", for example) and they should pop up somewhere in the long list of LCJS exports.
Next, inside LineSeries item, there should be a description of the exports general purpose, features, frequently used properties and example usage + a complete list of available methods, properties, etc. Here, you can once again utilize text search (Ctrl+F) to search for "cursor", which should lead you to LineSeries.setCursorResultTableFormatter - a method for configuring the formatting of cursor result table for a particular series.
In the best case, setCursorResultTableFormatter will include a convenient example usage block that you can immediately copy & paste to play with - but if not, then it will at least explain its primary purpose: allow supplying a function that formats the displayed text based on pointed XY coordinate.
Now, it is possible that you might encounter items in the API document, that do not contain the above described information - effectively hindering smooth navigation in the document. In this case your best bet is to try to find an example that can be used as reference code, join our Stackoverflow community, or contact support.
Below, you will also find a list of frequently asked questions, we hope these might quickly guide to the right place without having to study the document for a long time.
Do you have a question for us? Contact support
Most important series types supported by ChartXY:
For full reference, see ChartXY (all methods for adding series have same naming add...Series).
ChartXY also has a lot of features other than series:
ChartXY always has at least one X and Y axes.
The default Axis can be referenced with ChartXY.getDefaultAxisX and ChartXY.getDefaultAxisY. See Axis for features of axis.
ChartXY doesn't have a limit on number of axes. Additional axes can be created with ChartXY.addAxisX and ChartXY.addAxisY. Multiple Axes can be stacked on top of another, and axes can be positioned on either side of the chart (left, right, top, bottom, see AxisOptions).
The visual components of axis are:
Title. By default axis has no title. It can be enabled with Axis.setTitle.
Axis line. A single horizontal line for X axes, and vertical line for Y axes. It can be styled with Axis.setStrokeStyle.
Ticks. Labels that help understand the data visualized along an axis.
Highlighters. Can be used to highlight positions or areas on an axis.
See Scrolling and interval configuration for detailed information about management of axis interval.
Ticks are labels attached to the axis line that visualize the progression of values along the axis. A tick consists of three individually stylable parts:
There are currently three different ways of managing axis ticks:
Numeric ticks are enabled by default for all axes. Configuring the ticks is done with Axis.setTickStrategy.
Axis.setTickStrategy(AxisTickStrategies.Numeric, (strategy) => strategy
// Configure NumericTickStrategy
.setMinorFormattingFunction((tickPosition) => `X: ${tickPosition}`)
.setMinorTickStyle((tickStyle: VisibleTicks) => tickStyle
.setTickLength(12)
.setTickPadding(2)
)
)Frequently used API:
For full list of configuration API, see NumericTickStrategy.
Examples showcasing numeric axes:
DateTime ticks are enabled, as well as configured, with Axis.setTickStrategy.
Axis.setTickStrategy(AxisTickStrategies.DateTime, (strategy) => strategy
// Configure DateTimeTickStrategy
.setMinorTickStyle((tickStyle: VisibleTicks) => tickStyle
.setTickLength(12)
.setTickPadding(2)
)
)Frequently used API:
For full list of configuration API, see DateTimeTickStrategy.
Examples showcasing datetime axes:
Automatic creation of ticks can be disabled with Axis.setTickStrategy:
// Disable automatic axis ticks.
Axis.setTickStrategy(AxisTickStrategies.Empty)Custom ticks can be created with Axis.addCustomTick:
// Create custom ticks.
for (let x = 0; x < 100; x += 10) {
const tick = Axis.addCustomTick(UIElementBuilders.AxisTick)
}Frequently used CustomTick API:
dispose().Examples showcasing custom axis ticks:
Axis interval is the range of data values that are visible on the Axis, they are referred to as start and end.
By default, all axes fit the interval automatically to reveal all attached series. This behavior is called fitting scroll strategy.
Automatic scrolling behavior can be controlled by selecting the scroll strategy, with Axis.setScrollStrategy:
// Select progressive scroll strategy.
Axis.setScrollStrategy(AxisScrollStrategies.progressive)Following scroll strategies are supported:
undefined | automatic scrolling is disabled.Axis interval can be manually set with Axis.setInterval:
// Axis start = 0, end = 100.
Axis.setInterval(0, 100)However, if automatic scrolling is either 'fitting' or 'expansion' the configured axis interval might immediately be overridden.
Frequently used methods:
Two kinds of highlighters are supported:
Examples showcasing axis highlighters:
Auto cursor is a feature currently available in ChartXY, SpiderChart and PolarChart.
NOTE: Will be introduced to Chart3D in the near future - stay tuned!
Auto cursor is activated when the users mouse is over the chart. It automatically solves the nearest data point to the mouse, and displays it to the user over the chart in a result table.
Auto cursor can be configured in a variety of ways; on chart level, the cursor behavior and style can be specified using:
// Set auto cursor behavior.
ChartXY.setAutoCursorMode(AutoCursorModes.snapToClosest)
// Style auto cursor.
ChartXY.setAutoCursor((autoCursor) => autoCursor
.setGridStrokeXStyle(new SolidLine({
thickness: 1,
fillStyle: new SolidFill({ color: ColorRGBA( 255, 0, 0 ) })
}))
// ... use methods of AutoCursorXY here.
)On series level, the cursor behavior can be configured individually for each series:
'nearest-x', 'nearest', etc.).// Configure AutoCursor behavior per series.
LineSeries
.setCursorEnabled(true)
.setCursorInterpolationEnabled(false)
.setCursorSolveBasis('nearest-x')
.setCursorResultTableFormatter((builder, series, x, y) => builder
.addRow('Result table title')
.addRow('Pointing at:')
.addRow('X:', x.toFixed(1))
.addRow('Y:', y.toFixed(1))
)Auto cursor is made from three individually stylable parts:
// Example styling of AutoCursor.
ChartXY.setAutoCursor((autoCursor) => autoCursor
// Remove Y tick marker.
.disposeTickMarkerY()
// Hide Y grid line.
.setGridStrokeYStyle(emptyLine)
// Enable ResultTable text coloring based on pointed data point color (only supported by select series types, for example, PointSeries).
.setResultTableAutoTextStyle(true)
// Style ResultTable.
.setResultTable((resultTable) => resultTable
.setTextFont((font) => font
.setStyle('italic')
)
)
)Frequently used methods:
Examples showcasing auto cursor styling: