## 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](https://ukorvl.github.io/lightweight-charts-react-components/) to see the components in action.
## Table of Contents
- [Description](#description)
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Stable release](#stable-release)
- [Preview builds](#preview-builds)
- [Standalone browser build](#standalone-browser-build)
- [Usage](#usage)
- [Chart Container Sizing](#chart-container-sizing)
- [Examples](#examples)
- [Contributing](#contributing)
- [How to Contribute](#how-to-contribute)
- [Related Projects](#related-projects)
- [License](#license)
## Installation
### Stable release
Install the latest published version from npm:
```bash
npm install lightweight-charts-react-components lightweight-charts
```
### Preview builds
To test the latest unreleased version from `main`, install the preview build published via `pkg.pr.new`:
```bash
npm install https://pkg.pr.new/lightweight-charts-react-components@main lightweight-charts
```
Or choose a specific commit from `main` and install the preview build for that commit:
```bash
npm install https://pkg.pr.new/lightweight-charts-react-components@ lightweight-charts
```
For 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.
```html
```
## 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:
```tsx
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 (
);
};
export { App };
```
The following is an advanced example that demonstrates how to use custom scales, panes and multiple series in a single chart:
```tsx
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 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 (
);
};
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](https://tradingview.github.io/lightweight-charts/docs/plugins/pane-primitives) for the underlying Lightweight Charts plugin contract.
### Chart Container Sizing
The `Chart` component requires explicit width and height to render correctly. You can set these dimensions directly via the `options` prop or make the chart container scale to its parent size using the `containerProps` prop.
Note that the chart will automatically resize to fit its container.
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.
## Examples
The [examples](https://github.com/ukorvl/lightweight-charts-react-components/blob/main/examples/) app itself is a [Demo](https://ukorvl.github.io/lightweight-charts-react-components/) 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](https://github.com/ukorvl/lightweight-charts-react-components/blob/main/examples/src/samples).
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
1. Fork the repository and create a new branch for your changes.
2. Make your changes following the project guidelines.
3. Test your changes to ensure everything works as expected.
4. Submit a pull request.
For detailed contribution guidelines, please check out our [CONTRIBUTING.md](https://github.com/ukorvl/lightweight-charts-react-components/blob/main/CONTRIBUTING.md)
Thank you for helping improve this project!
## Related Projects
- [lightweight-charts](https://github.com/tradingview/lightweight-charts) - The original Lightweight Charts library by TradingView.
- [lightweight-charts-vue](https://github.com/ukorvl/lightweight-charts-vue) - Vue.js wrapper for Lightweight Charts.
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/ukorvl/lightweight-charts-react-components/blob/main/lib/LICENSE) file for details.
