timeScroll to pan back through history:
drag (or fling) to scroll the window into the past, and the chart stops auto-following until you
return to the live edge, where live-following resumes. One-finger plot scrubbing is unchanged.
Live example:
app/demo/time-scroll.tsx
in the example app.Pan back through history; auto-follow resumes at the live edge
data (or candles)
to scroll into — seed a few windows’ worth and keep your buffer longer than the visible window.
While scrolled back, the Y-range fits the visible window: only the points (or candles) inside
the frozen window shape the axis — newer data and the live price sit beyond the right edge and
don’t stretch it — so the axis re-fits the history you’re looking at as you pan. Back at the live
edge, the range folds the live value back in as usual.
Turning it back off
SettingtimeScroll back to false while scrolled back — or switching mode so your component
stops passing it — glides the window back to the live edge: a brief eased animation (it
decelerates onto live), not an instant jump. It never stays frozen at the previous scroll position,
so toggling time-scroll (or changing modes) is always a clean return to live, and re-enabling it
later starts from the live edge rather than the old frozen spot. This holds even when your line and
candle series carry different amounts of history: a frozen edge that would land before the active
series’ first point follows live instead of stranding the plot empty.
Tune that glide — or turn it off — with the returnToLive prop (a sibling of timeScroll, so it
survives timeScroll={false}):
true (the default) eases onto live over 450 ms; false snaps instantly (the pre-4.3 behavior);
{ duration } sets a custom length in milliseconds. It only governs this programmatic return —
flinging back to the live edge with the pan gesture keeps its own inertia.
With an external viewport, disabling timeScroll only
disables the gesture; it preserves the supplied scroll position. Clear viewport.end
or reset the leader to return to live.
Gestures
timeScroll: true uses the default drag-to-scroll gesture. Pass a TimeScrollConfig to pick the
activation:
"holdToScrub"(default) — a one-finger drag anywhere scrolls the timeline; scrubbing moves to a press-and-hold (Rainbow-style). A quick drag scrolls; hold, then drag, to scrub."axisDrag"— only a drag that starts on the bottom x-axis strip (“grab the time ruler”) scrolls. The plot area stays free, so a one-finger drag there scrubs immediately.
Hold duration (scrubHoldMs)
In holdToScrub, scrubHoldMs sets how long to press before scrub engages (so a quicker drag
scrolls instead). Higher = more deliberate scrub, fewer accidental scrubs while scrolling. Default
500.
Release momentum (fling)
By default, a quick drag keeps moving with decaying momentum after you lift your finger. Set
fling: false for a deliberate hard stop: the window remains exactly where the drag ends. This
does not change the live-edge snap zone, so releasing near the live edge still resumes
auto-following.
fling defaults to true. The example app’s Time scroll screen includes a Fling inertia
switch to compare both behaviors.
Overscroll (overscroll)
By default the window hard-stops at the data: the oldest point on the left, the live edge on the
right. Set overscroll to a fraction of the visible window (0–1) to drag past those bounds
into blank space, TradingView-style — pull the latest candle toward the middle to leave room on the
right, or pan left past loaded history (pairs well with onVisibleRangeChange paging while older
data lazy-loads in).
0 (hard stops).
Pinch-to-zoom (zoom)
Enable zoom for two-finger pinch-to-zoom of the visible window. Pinch out to zoom in (a
narrower window), pinch in to zoom out — anchored at the focal point between your fingers, so
the time under your fingers stays put. It composes with timeScroll: zoom level and scroll position
are independent, and you can pan a zoomed-in window. Pinch is two-finger, so it never competes with
the one-finger pan / scrub.
timeWindow / 8 and out to the full retained data span.
Pass a ZoomConfig to set them explicitly:
Reset zoom from a button
Both chart components expose aresetZoom() method through a
LiveChartHandle. Call it from any outside event to
clear the focal-anchored pinch window and return to the configured timeWindow at the live edge:
LiveChartSeries. Resetting clears both state values changed by a
focal pinch: the overridden window width and its shifted right edge. That means the chart resumes
following live data instead of staying parked at the pinch anchor while its width returns to
normal. Calling it again is a safe no-op. A paused chart remains paused, and the displayed width
uses the chart’s normal smoothing as it settles back to timeWindow.
The example app’s Time scroll screen includes a Reset zoom button and a live visible-window
readout so the behavior can be exercised directly. To also return the price scale and a panned
price window, call resetView() or show the floating resetButton.
Price panning (priceScroll)
With timeScroll the chart pans through time; with priceScroll it also pans through price.
Drag the plot vertically to move the price window up or down, and drag diagonally to move both
axes at once, TradingView-style free panning.
priceScroll rides on the "holdToScrub" time-scroll pan, so it needs timeScroll in that
(default) gesture mode. Two activation models:
"afterScale"(default) only pans price once the range was manually changed: a price-axis drag (yAxis.scaleGesture), a pinch, or an earlier price pan. Until then a vertical drag falls through, so a chart inside aScrollViewstill scrolls the page."always"claims every vertical drag on the plot. Use it when the chart is not inside a vertical scroller.
viewport.range: your shared value when you pass viewport, private state
otherwise. Unlike an app-written range it stays active while the chart follows live, so new data
streams in without moving the window, and the engine keeps it inside the chart’s hard bounds
(nonNegative, maxValue, minRange). A purely horizontal scroll never freezes the range, so
the Y auto-fit keeps following the visible window as before.
Travel is bounded: neither edge of the window moves more than maxOvershoot visible spans past
the fitted range (default 1; 0 keeps the data in view at all times). Release has no momentum.
yRangeScale. A snapKey or mode change clears
it too. The floating resetButton and resetView() return everything at
once.
The example app’s Time scroll screen has a Price scroll setting (Off / After scale /
Always).
Synced charts
LiveChart can adopt a pair of shared values through the experimental viewport
prop (false | ViewportConfig). Pass an object to enable external control, or
false/omit it to keep private gesture state. The same values receive its pan/pinch
gestures and drive its visible range
when your app writes them. Use separate pairs for each pane, choose one leader,
and copy the leader’s drawn renderOverlay scale (now, window) to its followers
with useAnimatedReaction. Set windowSmoothing: false on followers to avoid
easing that drawn width again.
With viewport, non-null overrides survive timeWindow changes and switching
timeScroll off. Call resetZoom() or clear the pair to return to the defaults.
Your app owns leadership and any mapping between clocks or gap-free index time.
For annotation editors, optional viewport.range fixes price bounds while end
is non-null, including before the first retained sample or in empty future space.
Clear range to restore automatic fitting; resetZoom() clears end/window
and makes the retained price bounds inactive.
The Time scroll demo includes a Fixed price range: Off / On setting for
this comparison. Choose Line or Candles, turn on Freeze feed, then use
History and Future space to compare automatic fitting. Press Return
live, enable Fixed price range, and repeat: the visible price bounds stay
fixed while the same data moves through the window. Turning the setting off
restores automatic fitting at the current position. Return live clears the
annotation viewport and price lock; turn off Freeze feed to resume the feed.
The same frozen feed and positions, with automatic fitting first and fixed price bounds second
LiveChartSeries does not yet support viewport.
Paging callbacks (onVisibleRangeChange, onReachStart)
To lazily page in history as the user scrolls/zooms back, two callbacks report the visible window:
onVisibleRangeChangefires (throttled to ~1 Hz) with the window’sstartSec/endSecand whether the chart isfollowingthe live edge.onReachStartis a one-shot edge trigger: it fires once when the left edge comes within one window-width of the earliest retained point, then re-arms after you move back out — the cue to load the next page of older data. When the fetched data extendsdata/candlesfurther back, it can fire again as you keep scrolling.
Full-width plot while scrolled (yAxis.float)
A normal chart reserves a right gutter for the price axis, so candles stop short of the edge. Pair
timeScroll with yAxis: { float: true } and the plot runs
full-width under a floating price axis — but only while you’re scrolled back. At the live edge
(the default state) the chart keeps its normal gutter so the latest candle and the badge don’t sit
under the floating labels; as soon as you scroll back, the plot expands under the axis so panned-in
candles aren’t cut off, and it reverts when you return to live.
Track the visible edge (badge.followViewEdge)
While scrolled back, the live price is off-screen — so the live badge, dot, and value line are
hidden by default (they’d mark a price that isn’t in view). Set
badge.followViewEdge so the badge, value
line, and live dot instead track the price at the visible window’s right edge — the last
price you can see — and snap back to the live value when you return to the live edge. The badge’s
momentum color is calculated at that same historical edge, so new live ticks cannot recolor a
stationary historical badge. With a positive windowBuffer /
windowBufferSeconds or an external viewport, those indicators stay on the
latest recorded point while it is still inside the visible time window, and only
pin to the edge after that point leaves. To keep the badge, dot, and value line
pinned at the off-screen live price instead (the pre-4.12 behavior), set
timeScroll={{ hideLiveOnScrollBack: false }}.
The plotted line is independent of those overlay settings: while scrolled back, it always ends
at the visible window’s right-edge value and never connects the historical window to the current
live price.
Keep the dot on the live point (dot.trackWhileParked)
The default live dot is pinned to the plot’s right edge, so while scrolled back it would sit on a
historical price — it’s hidden (and its pulse suppressed) instead. Set
dot.trackWhileParked and the dot tracks the true live
point while scrolled back or overscrolled: it stays visible at the live point’s x, keeps its
heartbeat pulse (it still marks an honest live position), and hides once the live point leaves
the visible window. This is most visible with overscroll — drag past the live edge into blank
space and the dot detaches from the plot edge, pulsing at the real last price.
hideLiveOnScrollBack (the badge and value line keep the default hide). The flag is ignored
with badge.followViewEdge — an edge-pinned dot must stay aligned with its badge. Off by
default; the example app’s Time scroll screen includes a Dot tracks live point switch.
Notes
- Both charts.
timeScrollandzoomare wired intoLiveChartandLiveChartSeries. In multi-series, each series’ dot / value label tracks its value at the visible right edge while scrolled (the dot rides the end of each line, not the live price). - Coexists with scrubbing. Plot-area scrub (and the order ticket)
work alongside time-scroll — the gestures are disambiguated by region (
axisDrag) or press-hold (holdToScrub). Pinch-zoom is two-finger, so it stays out of the one-finger gestures’ way. axisDragreserves the time ruler in both charts. Scrubbing excludes the bottom strip (the bottom inset or 44 layout points, whichever is larger), including stationary holds. Scrub the plot above it; drag the ruler to scroll.- See the
LiveChartreference andTimeScrollConfig/ZoomConfigfor every field.