lightweight-charts-react-components guide
Quick Start
Let the components manage chart and series creation and cleanup. Import components
and ref types from lightweight-charts-react-components; import native data, option,
and event types from lightweight-charts.
- Check versions against the compatibility table below. Read declared ranges
from the app's
package.json, then the installed versions from the version
field of node_modules/<package>/package.json for
lightweight-charts-react-components, lightweight-charts, react, and
react-dom. If the library is not installed, follow
Installation. Ensure chart rendering runs in the browser,
within the app's client boundary.
- For a basic static chart, start from the minimal chart below. Otherwise, read the
reference matching the requested behavior. Adapt its feed and UI; preserve its
data contract, component nesting, and API readiness handling.
- Choose one data owner: pass the complete dataset through
data for React-owned
updates, or use reactive={false} and the series API for frequent ticks.
Installation
Install the wrapper together with its lightweight-charts peer dependency, using
the project's package manager. React and React DOM must already be installed.
npm install lightweight-charts-react-components lightweight-charts
Minimal chart
import type { LineData, UTCTimestamp } from "lightweight-charts";
import {
Chart,
LineSeries,
TimeScale,
TimeScaleFitContentTrigger,
} from "lightweight-charts-react-components";
// Data must be sorted ascending by time with unique times (UTC seconds here).
export function SimpleLineChart({ data }: { data: LineData<UTCTimestamp>[] }) {
return (
// autoSize follows the container, which needs a nonzero height.
<Chart
options={{ autoSize: true }}
containerProps={{ style: { height: 300, width: "100%" } }}
>
<LineSeries data={data} />
<TimeScale>
<TimeScaleFitContentTrigger deps={[]} />
</TimeScale>
</Chart>
);
}
Examples and snippets (reference files)
Read the reference matching the user's outcome. Each contains a complete TypeScript
recipe, data and integration contracts, reasons for the architecture, failure modes,
and acceptance checks. Combine references when a task spans several outcomes; do
not load every reference for a simple chart.
| User request |
Reference |
| WebSocket candles, updating the current bar, stale history, excessive chart renders |
Market data and live updates |
| Older history on scroll, viewport jumps, symbol/interval changes, late API responses |
History and range selection |
| Candles plus volume, moving averages, oscillator panes, independent price scales |
Price, volume, and indicators |
| OHLC legend, hover details, missing data, tooltip positioning |
Hover legends and tooltips |
| Executions and signals, stop/target levels, click-to-place price lines |
Trade markers and price levels |
| Compare assets with different prices, fixed-baseline returns, toggle comparisons |
Performance comparison |
| Separate charts that share scrolling, zooming, and a crosshair |
Synchronized charts |
| Trading-session shading, pane backgrounds, custom drawing that follows zoom |
Session overlays and primitives |
| Options strikes, yield maturities, choosing a numeric or custom horizontal axis |
Numeric axes and chart types |
If no reference matches the request, tell the user that the skill has no recipe
for it. Then build the solution from the public components and the upstream
lightweight-charts API, applying the Quick Start rules and the edge cases below.
Skill compatibility
The recipes are verified against the reference versions below. These are the
tested baseline, not the latest available releases.
If an installed version differs from the reference version, compare it with the
compatibility range. Inside the range, recipes apply as written. Outside it,
tell the user about the mismatch before writing code, because breaking API
changes can affect the recipes, and verify every API the recipe uses against
the installed package.
| Dependency or environment |
Reference version |
Compatibility range and checks |
lightweight-charts-react-components |
2.6.1 |
Recipe target: >=2.6.1 <3. Other versions require checking installed exports, chart API refs, and reactive data behavior before adapting a recipe. |
lightweight-charts |
5.2.1 |
Declared peer: >=5.0.8 <6. |
| React and React DOM |
19.2.6 |
Declared peers: >=18.2 <20. Keep react and react-dom on matching versions and use the application's existing React instance. |
| Node.js |
— |
Package engines: >=18.14.0. The app's build tools can require a newer version. |
| Module system |
ESM |
ESM import entry only; there is no CommonJS require entry. |
| Rendering |
Browser |
Charts need the DOM and canvas. Render them on the client, never during server rendering. |
Common edge cases
- Chart sizing: Put DOM styles on
containerProps and give the chart a
nonzero height.
- Required ancestors: Headless chart children need a chart wrapper ancestor.
Markers, PriceLine, and SeriesPrimitive belong inside their series;
PriceScale, Watermark, and PanePrimitive require a Pane;
TimeScaleFitContentTrigger requires a TimeScale.
- API refs and readiness: Use
ref.current?.api() for the native API and
containerRef for the div. For Chart, use ChartApiRef<Time, IChartApi>.
.api() can initially return null; follow the recipe's readiness step before
imperative setup.
- Viewport resets: To preserve scroll/zoom, keep the chart's key stable and
live/history updates out of fit-trigger dependencies. Fit on initial load or a
deliberate reset. See range handling.
- Data updates: Use
data for React-owned updates, or reactive={false} and the
series API when per-tick React renders are measurably costly. Avoid mixing both.
Reactive data is always the complete dataset. With wrapper 2.6.1 and
Lightweight Charts 5.2.1, series.data() reconstructs candle and line objects;
the wrapper's earlier-item reference comparison therefore sends multi-bar tail
updates through setData(), even when React keeps earlier references stable.
Keep data immutable, but use the chart-owned reactive={false} recipe and
explicit series.update(bar) when incremental writes are required. See
live updates.
Source
Adapted from ukorvl/lightweight-charts-react-components
at commit 0368191127568e48aef6f7bda2ff3900e8e24756. Original author: ukorvl.
The MIT license and all nine reference recipes are retained. Local
corrections in live updates reject
malformed timestamps and explain the tested versions' reactive-update limitation;
session overlays clarifies the
primitive update callback.
The other seven references and MIT notice are unchanged. This catalog copy adds
source attribution and operational boundaries; it does not imply TradingView
endorsement.
Recipes generate application code and can change dependencies. Follow the user's
requested scope and the host's approval policy. Feed access belongs to the app's
separately authorized adapter; keep credentials out of client code. Trade markers
are visual annotations, not order execution or server-side alerts. Use synthetic
data for local checks and report browser/feed behavior that remains untested.
1---2name: lightweight-charts-react-components3description: lightweight-charts-react-components recipes for TradingView lightweight-charts in React. Candlestick, line, and area series; volume and indicator panes; realtime WebSocket updates; infinite history on scroll; crosshair OHLC legends and tooltips; trade markers and price lines; synchronized charts; numeric options and yield-curve axes. Use when adding or fixing a financial or trading chart in a React app, or when the user mentions lightweight-charts, TradingView charts in React, or this package.4license: MIT5metadata:6 author: ukorvl7 version: "1.0"8 source: https://skillmd.com/skills/github/lightweight-charts-react-components9 upstream: "https://github.com/ukorvl/lightweight-charts-react-components/tree/0368191127568e48aef6f7bda2ff3900e8e24756/skills/lightweight-charts-react-components"10---1112# lightweight-charts-react-components guide1314## Quick Start1516Let the components manage chart and series creation and cleanup. Import components17and ref types from `lightweight-charts-react-components`; import native data, option,18and event types from `lightweight-charts`.19201. Check versions against the compatibility table below. Read declared ranges21 from the app's `package.json`, then the installed versions from the `version`22 field of `node_modules/<package>/package.json` for23 `lightweight-charts-react-components`, `lightweight-charts`, `react`, and24 `react-dom`. If the library is not installed, follow25 [Installation](#installation). Ensure chart rendering runs in the browser,26 within the app's client boundary.272. For a basic static chart, start from the minimal chart below. Otherwise, read the28 reference matching the requested behavior. Adapt its feed and UI; preserve its29 data contract, component nesting, and API readiness handling.303. Choose one data owner: pass the complete dataset through `data` for React-owned31 updates, or use `reactive={false}` and the series API for frequent ticks.3233### Installation3435Install the wrapper together with its `lightweight-charts` peer dependency, using36the project's package manager. React and React DOM must already be installed.3738```sh39npm install lightweight-charts-react-components lightweight-charts40```4142### Minimal chart4344```tsx45import type { LineData, UTCTimestamp } from "lightweight-charts";46import {47 Chart,48 LineSeries,49 TimeScale,50 TimeScaleFitContentTrigger,51} from "lightweight-charts-react-components";5253// Data must be sorted ascending by time with unique times (UTC seconds here).54export function SimpleLineChart({ data }: { data: LineData<UTCTimestamp>[] }) {55 return (56 // autoSize follows the container, which needs a nonzero height.57 <Chart58 options={{ autoSize: true }}59 containerProps={{ style: { height: 300, width: "100%" } }}60 >61 <LineSeries data={data} />62 <TimeScale>63 <TimeScaleFitContentTrigger deps={[]} />64 </TimeScale>65 </Chart>66 );67}68```6970## Examples and snippets (reference files)7172Read the reference matching the user's outcome. Each contains a complete TypeScript73recipe, data and integration contracts, reasons for the architecture, failure modes,74and acceptance checks. Combine references when a task spans several outcomes; do75not load every reference for a simple chart.7677| User request | Reference |78| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |79| WebSocket candles, updating the current bar, stale history, excessive chart renders | [Market data and live updates](references/market-data-and-live-updates.md) |80| Older history on scroll, viewport jumps, symbol/interval changes, late API responses | [History and range selection](references/history-and-range-selection.md) |81| Candles plus volume, moving averages, oscillator panes, independent price scales | [Price, volume, and indicators](references/price-volume-and-indicators.md) |82| OHLC legend, hover details, missing data, tooltip positioning | [Hover legends and tooltips](references/hover-legends-and-tooltips.md) |83| Executions and signals, stop/target levels, click-to-place price lines | [Trade markers and price levels](references/trade-markers-and-price-levels.md) |84| Compare assets with different prices, fixed-baseline returns, toggle comparisons | [Performance comparison](references/performance-comparison.md) |85| Separate charts that share scrolling, zooming, and a crosshair | [Synchronized charts](references/synchronized-charts.md) |86| Trading-session shading, pane backgrounds, custom drawing that follows zoom | [Session overlays and primitives](references/session-overlays-and-primitives.md) |87| Options strikes, yield maturities, choosing a numeric or custom horizontal axis | [Numeric axes and chart types](references/numeric-axes-and-chart-types.md) |8889If no reference matches the request, tell the user that the skill has no recipe90for it. Then build the solution from the public components and the upstream91`lightweight-charts` API, applying the Quick Start rules and the edge cases below.9293### Skill compatibility9495The recipes are verified against the reference versions below. These are the96tested baseline, not the latest available releases.9798If an installed version differs from the reference version, compare it with the99compatibility range. Inside the range, recipes apply as written. Outside it,100tell the user about the mismatch before writing code, because breaking API101changes can affect the recipes, and verify every API the recipe uses against102the installed package.103104| Dependency or environment | Reference version | Compatibility range and checks |105| ------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |106| `lightweight-charts-react-components` | `2.6.1` | Recipe target: `>=2.6.1 <3`. Other versions require checking installed exports, chart API refs, and reactive data behavior before adapting a recipe. |107| `lightweight-charts` | `5.2.1` | Declared peer: `>=5.0.8 <6`. |108| React and React DOM | `19.2.6` | Declared peers: `>=18.2 <20`. Keep `react` and `react-dom` on matching versions and use the application's existing React instance. |109| Node.js | — | Package engines: `>=18.14.0`. The app's build tools can require a newer version. |110| Module system | ESM | ESM `import` entry only; there is no CommonJS `require` entry. |111| Rendering | Browser | Charts need the DOM and canvas. Render them on the client, never during server rendering. |112113## Common edge cases114115- **Chart sizing:** Put DOM styles on `containerProps` and give the chart a116 nonzero height.117- **Required ancestors:** Headless chart children need a chart wrapper ancestor.118 `Markers`, `PriceLine`, and `SeriesPrimitive` belong inside their series;119 `PriceScale`, `Watermark`, and `PanePrimitive` require a `Pane`;120 `TimeScaleFitContentTrigger` requires a `TimeScale`.121- **API refs and readiness:** Use `ref.current?.api()` for the native API and122 `containerRef` for the div. For `Chart`, use `ChartApiRef<Time, IChartApi>`.123 `.api()` can initially return null; follow the recipe's readiness step before124 imperative setup.125- **Viewport resets:** To preserve scroll/zoom, keep the chart's key stable and126 live/history updates out of fit-trigger dependencies. Fit on initial load or a127 deliberate reset. See [range handling](references/history-and-range-selection.md).128- **Data updates:** Use `data` for React-owned updates, or `reactive={false}` and the129 series API when per-tick React renders are measurably costly. Avoid mixing both.130 Reactive `data` is always the complete dataset. With wrapper 2.6.1 and131 Lightweight Charts 5.2.1, `series.data()` reconstructs candle and line objects;132 the wrapper's earlier-item reference comparison therefore sends multi-bar tail133 updates through `setData()`, even when React keeps earlier references stable.134 Keep data immutable, but use the chart-owned `reactive={false}` recipe and135 explicit `series.update(bar)` when incremental writes are required. See136 [live updates](references/market-data-and-live-updates.md).137138## Source139140Adapted from [ukorvl/lightweight-charts-react-components](https://github.com/ukorvl/lightweight-charts-react-components/tree/0368191127568e48aef6f7bda2ff3900e8e24756/skills/lightweight-charts-react-components)141at commit `0368191127568e48aef6f7bda2ff3900e8e24756`. Original author: ukorvl.142The [MIT license](LICENSE) and all nine reference recipes are retained. Local143corrections in [live updates](references/market-data-and-live-updates.md) reject144malformed timestamps and explain the tested versions' reactive-update limitation;145[session overlays](references/session-overlays-and-primitives.md) clarifies the146primitive update callback.147The other seven references and MIT notice are unchanged. This catalog copy adds148source attribution and operational boundaries; it does not imply TradingView149endorsement.150151Recipes generate application code and can change dependencies. Follow the user's152requested scope and the host's approval policy. Feed access belongs to the app's153separately authorized adapter; keep credentials out of client code. Trade markers154are visual annotations, not order execution or server-side alerts. Use synthetic155data for local checks and report browser/feed behavior that remains untested.