lightweight-charts-react-components
v2.8.0
Published
React components for Lightweight Charts
Maintainers
Readme
Description
This library is a set of React components that wraps the Lightweight-charts library. It provides a simple declarative way to use the Lightweight-charts library in your React application. Check out the Demo to see the components in action.
Table of Contents
Installation
Stable release
Install the latest published version from npm:
npm install lightweight-charts-react-components lightweight-chartsPreview builds
To test the latest unreleased version from main, install the preview build published via pkg.pr.new:
npm install https://pkg.pr.new/lightweight-charts-react-components@main lightweight-chartsOr choose a specific commit from main and install the preview build for that commit:
npm install https://pkg.pr.new/lightweight-charts-react-components@<commit-hash> lightweight-chartsFor security reasons, preview builds are published only from commits pushed to main. Pull request builds are not published.
Standalone browser build
The standalone version is also available for use in the browser without a build step. The library expects global React, ReactDOM, and LightweightCharts variables to be available in the global scope.
<head>
<script
src="https://unpkg.com/react@18/umd/react.production.min.js"
crossorigin
></script>
<script
src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
crossorigin
></script>
<script
src="https://unpkg.com/lightweight-charts/dist/lightweight-charts.standalone.production.js"
crossorigin
></script>
<script
src="https://unpkg.com/lightweight-charts-react-components/dist/lightweight-charts-react-components.standalone.js"
crossorigin
></script>
</head>
<body>
<script>
const { Chart, LineSeries } = LightweightChartsReactComponents;
</script>
</body>Usage
The library provides a set of components that you can use in your React application. Here is a simple example of how to use the Chart and LineSeries components:
import React from "react";
import { Chart, LineSeries } from "lightweight-charts-react-components";
const data = [
{ time: "2023-01-01", value: 100 },
{ time: "2023-01-02", value: 101 },
{ time: "2023-01-03", value: 102 },
];
const App = () => {
return (
<Chart>
<LineSeries data={data} />
</Chart>
);
};
export { App };The following is an advanced example that demonstrates how to use custom scales, panes and multiple series in a single chart:
import React from "react";
import {
Chart,
LineSeries,
HistogramSeries,
PriceScale,
TimeScale,
TimeScaleFitContentTrigger,
Pane,
} from "lightweight-charts-react-components";
const data = [
{ time: "2023-01-01", value: 100 },
{ time: "2023-01-02", value: 101 },
{ time: "2023-01-03", value: 102 },
];
const volumeData = [
{ time: "2023-01-01", value: 1000, color: "rgba(0, 150, 136, 0.5)" },
{ time: "2023-01-02", value: 1100, color: "rgba(0, 150, 136, 0.5)" },
{ time: "2023-01-03", value: 1200, color: "rgba(0, 150, 136, 0.5)" },
];
const chartOptions = {
// Important to set width and height for the chart
// Otherwise make chart container scale to its parent size by using containerProps, like:
// <Chart containerProps={{ style: { width: '100%', height: '100%' } }} />
// Chart itself automatically resizes to fit its container
width: 600,
height: 400,
// Chart options can be customized here
};
const priceScaleOptions = {
// Price scale options can be customized here
};
const App = () => {
return (
<Chart options={chartOptions}>
<Pane stretchFactor={2}>
<LineSeries data={data} />
<PriceScale id="left" options={priceScaleOptions} />
</Pane>
<Pane>
<HistogramSeries data={volumeData} />
</Pane>
<TimeScale>
<TimeScaleFitContentTrigger deps={[]} />
</TimeScale>
</Chart>
);
};
export { App };PriceScale customizes a price scale of the pane it is rendered in. To give a series its own scale in the same pane (for example, volume under candlesticks), set a custom priceScaleId on the series and render PriceScale with the same id inside that series. A custom price scale exists only after a series that uses it is added, so nest PriceScale in that series or place it after the series:
import React from "react";
import {
Chart,
CandlestickSeries,
HistogramSeries,
Pane,
PriceScale,
} from "lightweight-charts-react-components";
const candles = [
{ time: "2023-01-01", open: 100, high: 105, low: 98, close: 103 },
{ time: "2023-01-02", open: 103, high: 107, low: 101, close: 102 },
];
const volume = [
{ time: "2023-01-01", value: 1000 },
{ time: "2023-01-02", value: 1100 },
];
const App = () => {
return (
<Chart options={{ width: 600, height: 400 }}>
<Pane>
<CandlestickSeries data={candles} />
<HistogramSeries data={volume} options={{ priceScaleId: "volume" }}>
<PriceScale id="volume" options={{ scaleMargins: { top: 0.8, bottom: 0 } }} />
</HistogramSeries>
</Pane>
</Chart>
);
};
export { App };Pane-wide overlays that belong to a whole pane rather than a single series can be mounted declaratively with PanePrimitive inside Pane. This works well for session bands, pane-scoped annotations, and background highlights that need access to both the chart and the target pane. See the PanePrimitives sample in the examples app for a full working example, and the upstream pane primitives documentation for the underlying Lightweight Charts plugin contract.
Updating Series Data
Use YYYY-MM-DD with a zero-padded month and day for string dates, or pass a BusinessDay object. Lightweight Charts 5.3 and later also enforce this format in production builds.
By default, series components are reactive: data is the complete dataset, and every new array is synced to the chart. To keep live updates cheap, the wrapper calls series.update() instead of series.setData() when the new array only appends one item with a later time or replaces the last item with one of the same time, and every earlier item keeps the same object reference. Anything else, such as a refetch, a historical correction, or an array rebuilt from new objects, replaces the whole dataset with setData(). Treat data items as immutable: an item changed in place keeps its reference, so the change is not detected. If your feed changes items in place, set alwaysReplaceData.
For high-frequency feeds where re-rendering React on every tick is too costly, pass reactive={false}, which uses data only to initialize the series, and push ticks through the series API ref with ref.current?.api()?.update(bar). Do not mix both approaches on the same series. See the agent skill's live updates guide for complete recipes.
Chart Container Sizing
The Chart component needs a nonzero container size. Set fixed dimensions through
options, or enable options={{ autoSize: true }} and size the container through
containerProps. Automatic resizing requires autoSize: true.
There may be cases where the chart's parent HTML element has no size defined (for example, when the parent is a flex container with no defined height). In such cases, you need to ensure that the parent element has a defined size (width and height) for the chart to render properly.
Agent skill
The project comes with an agent skill that provides recipes for common charting scenarios and guides on how to integrate the library into React applications. The skill is designed to help coding agents understand the library's design choices and common edge cases, making it produce higher-quality code when using the library.
For more information on how to use the skill, please refer to the skill readme.
Examples
The examples app itself is a Demo web application, but it contains a lot of examples of how to use the library. You can find the source code in the samples folder. You can run and test the code locally by cloning the repository and running the examples app.
Contributing
We welcome contributions of all kinds! Whether it's fixing bugs, adding new features, improving examples, or suggesting ideas—your help is greatly appreciated.
How to Contribute
- Fork the repository and create a new branch for your changes.
- Make your changes following the project guidelines.
- Test your changes to ensure everything works as expected.
- Submit a pull request.
For detailed contribution guidelines, please check out our CONTRIBUTING.md Thank you for helping improve this project!
Related Projects
- lightweight-charts - The original Lightweight Charts library by TradingView.
License
This project is licensed under the MIT License - see the LICENSE file for details.
