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.
The Community License is available to non-commercial users. When used this way there will be a LightningChart JS logo on each chart.
There is a small performance drop when the chart is running without a license key compared to running with a valid license.
By downloading, installing, copying or otherwise using LightningChart®JS, you are agree to be bound by the terms of the LICENSE agreement.
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 behave 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.
Application deployment license requires a known company name and an application name, these can't be exactly same. So in case of there being a company named "Example Co" they couldn't have an application name of "Example Co" they would need to edit it a little bit for example "Example Co App". The application name registered in the Application Deployment license doesn't have to be visible in the application itself, it's only required to be visible in the application source code.
To use your LightningChart JS license, you must supply license information when lightningChart is initiated.
This license information is slightly different depending on which license type is used.
Community License is used automatically whenever you use the product without supplying a license.
// Create an instance of LightningChart for creation of charts.
// ----- Using Community License -----
const lc = lightningChart()
This license looks like xxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx.
Development licenses are only used for development purposes and require internet connection.
// Create an instance of LightningChart for creation of charts.
// ----- Using Development License -----
const lc = lightningChart({
license: `xxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx`
})
This license looks like xxxx-xxxx....xxxx-xxxx...xxx-xxxx...xxx.
Web deployment license is the most common deployment license type and it's used when deploying to a known domain.
// Create an instance of LightningChart for creation of charts.
// ----- Using Web Deployment License -----
const lc = lightningChart({
license: `xxxx-xxxx....xxxx-xxxx...xxx-xxxx...xxx`
})
This license looks like xxxx-xxxxx...xxxx-xxxxx...xxxx-xxxxx...xxxx.
Application deployment license requires known application name and company name to be supplied with the license key. The application name and company name are requested during/after purchase of a Application Deployment license and are delivered with the license. This license type is used for deploying applications.
// Create an instance of LightningChart for creation of charts.
// ----- Using Application Deployment License -----
const lc = lightningChart({
license: `xxxx-xxxxx...xxxx-xxxxx...xxxx-xxxxx...xxxx`,
licenseInformation: {
appTitle: 'My Application',
company: 'My Company'
}
})
See LightningChartOptions for more 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? See more frequently asked questions here or contact us here.
LightningChart JS comes with a handful of built-in themes. Many times in actual use cases, you however need to adjust the complete chart style to fit into the frontend application at hand.
This can be done using the style API. All visual parts of LightningChart can be dynamically re-styled during runtime, using methods such as LineSeries.setStrokeStyle.
Then, there is also an alternative way to configure the style of LightningChart, which is to modify the used Theme. A LightningChart Theme is effectively a long list of style properties that are used as the default style before any run-time modifications. There are two ways of modifying Themes:
const chart = lightningChart().ChartXY({
theme: {
...Themes.darkGold,
// Bright red title color for ChartXY
chartXYTitleFillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) }),
// Dark red series background color for ChartXY
chartXYSeriesBackgroundFillStyle: new SolidFill({ color: ColorRGBA(50, 0, 0) }),
},
})
const series = chart.addLineSeries()
series.addArrayY(new Array(10).fill(0).map((_) => Math.random()))
It is possible to completely control all the default styles of different parts of LightningChart by creating a complete definition of the Theme interface. This, however, is quite an extensive process as the interface has over 200 properties.
To make this easier, we have separated the topic of custom theme creation into an isolated open-source community. This can be found at GitHub under lcjs-themes. The repository includes some tools for making simple custom Themes from a handful of inputs, which can also be studied to reduce the workload of making your completely own custom theme.
import { makeLightningChartThemeFlat } from "@arction/lcjs-themes"
import { ColorHEX, lightningChart, SolidFill } from "@arction/lcjs"
const flatDarkTheme = makeLightningChartThemeFlat({
backgroundColor: ColorHEX('141619'),
textColor: ColorHEX('c5ced7'),
dataColors: [ColorHEX('e24d42')],
axisColor: ColorHEX('00000000'),
gridLineColor: ColorHEX('2c3235'),
uiBackgroundColor: ColorHEX('141619'),
uiBorderColor: ColorHEX('ffffff'),
fontFamily: 'Verdana',
})
const chart = lightningChart().ChartXY({ theme: flatDarkTheme })
chart.addLineSeries().addArrayY(new Array(10).fill(0).map(_ => Math.random()))
chart.addLegendBox().add(chart)
Glow and shadow effects are enabled in some Themes by default. They can be easily disabled with disableThemeEffects.
The minimum supported TypeScript version is currently 4.1 (released Nov 19 2020).
This is likely due to text pixel snapping, which is a feature for improving text sharpness and visual quality. Unfortunately in some applications (especially those with a slow scrolling axis) this introduces the side effect of text moving between pixels rapidly.
Please experiment with disabling text pixel snapping by following instructions here.
Some features of LightningChart JS depend on non-JavaScript assets that are distributed along-side the library but not bundled with it. Here are some examples:
In order to use these features, the user has to setup a file server that hosts these resources, and inform LightningChart of the URL to this file server.
For more detailed instructions, see section on resourcesBaseUrl
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:
Please refer to documentation of Axis class
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.
.setTickMarkerYVisible(false)
// 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: