lightweight-charts-react-components Guide

This skill guides financial chart implementation with lightweight-charts-react-components. It covers realtime candles, history pagination, indicator panes, OHLC tooltips, visual trade markers, synchronized charts, and diagnosis of component nesting or API readiness. The wrapper manages chart and series creation and cleanup, while the application supplies data through its authorized adapter.

The workflow begins by inspecting package metadata, installed dependencies, existing chart components, and time-series contracts. Components and ref types come from the wrapper; native data, options, and event types come from lightweight-charts. A basic chart needs ascending, unique timestamps, a nonzero-height container, and browser rendering within the application's client boundary.

Use it to add or repair charts built with this wrapper, especially when live updates, history prepends, scrolling, zoom, or multiple panes interact. Select the recipe matching the requested outcome rather than loading every reference. Available recipes cover market updates, history and ranges, price and indicators, legends, annotations, performance comparisons, synchronization, overlays, and numeric axes.

It does not fetch broker data or execute trades. Visual markers and price levels do not provide order execution, durable storage, financial advice, or broker integrations. Feed aggregation, authentication, replay or cursor recovery, and response validation remain the application's adapter responsibilities. General React optimization and Python visualization belong to other tools. If a request lacks a matching recipe, explain that gap and use the public component and native chart APIs with the same lifecycle rules.

Choose a single data owner. React-owned updates pass the complete dataset through data. For frequent ticks where React renders are measurably costly, use reactive={false} and the series API. Mixing the two ownership models is discouraged.

The reactive incremental path calls update() only when previous items retain their object references and the new array either replaces the last item at the same timestamp or appends exactly one new timestamp. Other changes, including alwaysReplaceData, use setData(). Copy data once at the boundary rather than cloning or mutating earlier items.

Keep the chart key stable to preserve the viewport. Live and history changes stay outside fit-trigger dependencies; fitting happens on initial load or a deliberate reset. A single-series index adjustment cannot restore ranges across unaligned multi-series histories, which require the union-of-times approach.

Component ancestry is explicit: markers, price lines, and series primitives belong inside their series. Price scales, watermarks, and pane primitives need a pane. The fit-content trigger belongs inside a time scale. DOM styles go through containerProps. Native access uses ref.current?.api(), which can initially return null; imperative setup waits for readiness. The container div has its own containerRef.

Recipes provide complete TypeScript examples, architectural reasons, failure cases, and acceptance checks. Result reporting distinguishes observed checks from expected behavior and calls out untested browser or feed behavior. Synthetic data can support a local chart check without connecting a broker.

The application requires React, React DOM, browser DOM and canvas, the wrapper, and its chart peer dependency. Installation uses the application's selected package manager; the npm example is:

npm install lightweight-charts-react-components lightweight-charts

The recipe baseline is wrapper 2.6.1, targeting versions from 2.6.1 up to but excluding 3. The native chart baseline is 5.2.1 with peer range 5.0.8 through versions below 6. React and React DOM use matching versions within 18.2 through versions below 20; the reference version is 19.2.6. Node.js must satisfy the package engine minimum of 18.14.0, with application tooling potentially requiring more. The module entry is ESM only, and charts cannot render solely on the server.

Versions outside the supported ranges require an explicit mismatch report and inspection of the installed APIs before adaptation. Dependency installation follows the host's approval policy. Credentials stay out of client code and logs; rendering does not authorize deployments, orders, or server-side alerts. Real adapters are inspected before use because they may send symbol and interval requests to a selected feed.