ta.valuewhen in Pine Script: Occurrences, Captured Values, and Repainting

ta.valuewhen(condition, source, occurrence) returns the source value from a selected occurrence of a true condition. Occurrence zero is the latest matching bar, including the current bar if its condition is true.

Count occurrences, not bars

The occurrence argument accepts a nonnegative simple integer, including compatible input or constant integers; it need not be a literal written directly in the call. If there are not enough matching occurrences, the numeric result is unavailable.

A condition that remains true for five bars creates five occurrences. To capture only the transition into a state, define a transition event rather than passing the persistent state. ta.barssince() answers a different question: how many bars have passed since the latest true condition.

Capture a moving-average cross

This retained fragment requires a version declaration and indicator() declaration around it; it is not a standalone script:

// Define your moving averages
fastMA = ta.sma(close, 20)
slowMA = ta.sma(close, 50)

// Detect the golden cross
goldenCross = ta.crossover(fastMA, slowMA)

// Capture the price when it happened
priceAtGoldenCross = ta.valuewhen(goldenCross, close, 0)

// Plot it as a reference line
plot(priceAtGoldenCross, color=color.yellow, title="Golden Cross Price")

The 20/50 averages define this example's cross; these periods are not a universal definition of a golden cross. The plotted level updates when the event is true and remains unavailable before the first event.

The next fragment extends those same variables:

// Get the price from 3 bars before the golden cross
priceBeforeCross = ta.valuewhen(goldenCross, close[3], 0)

// Get the volume when the cross happened
volumeAtCross = ta.valuewhen(goldenCross, volume, 0)

// Compare current price to the cross price
percentChange = (close - priceAtGoldenCross) / priceAtGoldenCross * 100

Placing [3] inside the source captures the close three bars before the matching event. It differs from applying [3] to the returned valuewhen series, which reads that series as it stood three chart bars ago. Percentage change also needs an available, nonzero reference price before it is meaningful.

Conditions and pivot confirmation

This further fragment depends on fastMA from the first example:

// Complex condition: price above MA and RSI oversold
complexCondition = close > fastMA and ta.rsi(close, 14) < 30

// Capture the exact price when both conditions align
entryPrice = ta.valuewhen(complexCondition, close, 0)

It captures every bar satisfying both tests, not only the first entry into that state. entryPrice is a variable name here, not an actual broker fill.

For pivots, use an explicit boolean condition such as “pivot is not unavailable” and capture the pivot value itself. A pivot function returns a price, not a boolean in Pine v6. Capturing the confirmation bar's high instead would generally capture a different price from the earlier pivot.

Evaluate consistently and control data timing

Call history-dependent functions consistently on every bar. Avoid calling ta.valuewhen() only inside an occasional conditional branch and assuming it has the same history as an unconditional call.

A condition or source can change during an open realtime bar, so its captured value can change as well. For chart-bar events, closed-bar confirmation can stabilize that event. Setting calc_on_every_tick=false is a strategy setting, not a universal solution for indicators or future-data leakage.

For higher-timeframe requests, lookahead_off alone does not guarantee stable realtime values. The confirmed-HTF pattern uses an offset expression with lookahead_on and applies only when the requested timeframe is higher. See TradingView's repainting guide and function reference.

Captured indicator values are useful for comparison and diagnostics. They do not by themselves establish support, resistance, or an executable profitable strategy.