Supertrend: Trace ATR Bands, Ratchets, and Direction Flips

The familiar colored line is not simply midpoint plus or minus ATR. It depends on true range, Wilder ATR, band carry-forward rules, the previous active band, and strict crossing logic.

Supertrend builds basic ATR bands around the bar midpoint, ratchets them with previous-band rules, and activates one band according to a recursive direction state. By the end of this tutorial, you will be able to calculate the line, audit its hidden state, reproduce its warm-up and boundary conventions, and explain why another platform can disagree.

Data note: every chart and number in this article uses deterministic synthetic teaching data. No historical return or investment-performance claim is made.

Start with the question the indicator actually answers

A trend system is useful only when its output has a precise meaning. The current package asks one bounded measurement question and refuses to turn a chart state into a forecast.

Supertrend builds basic ATR bands around the bar midpoint, ratchets them with previous-band rules, and activates one band according to a recursive direction state.

Supertrend mechanism map

The map is the implementation checklist: validate the bar, calculate the intermediate state, apply the exact boundary rule, then publish an aligned output with its diagnostic evidence.

Formula and selected convention

BasicUpper_t=HL2_t+m\,ATR_t,\qquad BasicLower_t=HL2_t-m\,ATR_t

The final upper resets to the basic upper when that basic value is lower or the previous close was above the previous final upper; otherwise it carries. The final lower resets symmetrically when the basic lower is higher or the previous close was below the previous final lower. The active line flips only when close strictly crosses the opposite final band.

Defaults are teaching choices rather than universal laws:

Parameter	Package default
`period`	`10`
`multiplier`	`3.0`

Worked numerical example

If the basic upper is 108, the prior final upper is 110, and the prior close is 105, the new final upper ratchets down to 108. If the current close then exceeds 108 while the upper band was active, direction flips up and the final lower becomes the active line.

The hand result is deliberately small enough to recalculate without either implementation. The canonical fixture then extends the same rules across five long, topic-specific paths.

Supertrend exact canonical trace

From data contract to executable state

Use finalized, chronological observations with one declared source field, session calendar, time zone, and adjustment basis. Reject non-finite values, malformed high/low geometry, and invalid parameters. Do not sort inside the numeric kernel, fill missing bars with zero, or splice adjusted and unadjusted history.

The implementation returns one aligned entry per input row. Warm-up stays None in Python and null in TypeScript. A revision to historical input invalidates the recursive or rolling suffix from the earliest changed row.

Rendering system map…

Implementation walkthrough

The Python and TypeScript files favor direct state variables over clever vectorization. That makes seed, tie, clamp, displacement, and reversal behavior reviewable. Both languages read the same fixture and preserve the same null, numeric, string, and boolean semantics.

Complexity is linear in the number of observations. The reference code is optimized for readability; a production streaming implementation can retain only the active rolling/recursive state after validating parity.

Reconcile a platform disagreement systematically

Dimension	This package	Maintained-platform context	What to compare
ATR	Wilder-smoothed true range	TradingView defines Supertrend from ATR	A different ATR seed changes every downstream band.
Initial state	Down at first ATR value	TradingView documents down until ATR is available	The first active band is part of the contract.
Crossing	Strict crossing flips; equality holds	TradingView uses close > upper and close < lower	Near-band comparisons require exact inequality rules.

Start at the first row where the two outputs diverge. Compare source fields and parameters first, then the previous intermediate state, and only then the published line. This avoids treating a documented convention difference as a numerical defect.

Explore the exact state

Open the guided Supertrend playground. The initial state is already informative. Choose a scenario, scrub or step to a named checkpoint, compare the visible diagnostics, and inspect the last 12 published rows.

The lab uses 180 observations in each of five scenarios, not a tiny decorative sample. A recent-60, recent-120, or complete-history focus keeps the denser path readable. Reduced-motion Play advances one observation without starting a timer.

Use the five-scenario atlas

Lesson	Scenario ID	What the controlled path isolates
Down-to-up strict crossing	`down-to-up-cross`	The initial down state persists until close strictly exceeds the final upper band.
Upper and lower ratchets	`upper-lower-ratchets`	Long shelves reveal when basic bands reset a final band and when the previous band carries forward.
ATR expansion shock	`atr-expansion-shock`	A volatility burst widens basic bands before the recursive final-band rules decide what remains active.
Strict-equality and whipsaw boundary	`whipsaw-boundary`	Alternating near-band closes show that equality holds direction while strict crossings flip it.
Responsive 7 × 1.5 comparison	`responsive-band-comparison`	A shorter ATR and smaller multiplier tighten bands and increase state sensitivity without changing the formula.

Each path contains five checkpoints: first guided state, transition, boundary, platform reconciliation, and mature-state audit. These labels explain deterministic calculation state; they do not classify future market behavior.

A production debugging ladder

Verify finalized input fields, chronological order, calendar, time zone, and adjustment basis.
Verify parameter values and the first-ready index.
Trace TR, ATR, basic bands, final-band ratchets, previous active band, and strict crossing.
Compare the shared fixture at the first divergent row.
Recalculate one checkpoint independently before changing code.
Record the convention version with every persisted output.

Boundaries that cause real implementation drift

ATR seed and smoothing convention change every downstream band.
Equality with a band does not flip direction in this package; the cross is strict.
Different platforms initialize direction differently before and at the first ATR value.

Supertrend boundary map

The strongest reconciliation workflow compares the first valid index, a steady-state row, an equality boundary, a reversal or reset, and the complete aligned suffix—not merely the last visible chart point.

Compare the family question, not the chart color

Parabolic SAR accelerates toward an extreme point. Supertrend offsets price by volatility and ratchets two candidate bands. Similar chart roles do not make their states interchangeable.

Neighboring indicators can display a similar bullish/bearish state while measuring different inputs. Agreement is not independent confirmation when the systems reuse the same prices and smoothing primitives.

Testing proves calculation, not profitability

The release checks cover:

all-five-scenario Python/TypeScript parity;
exact first-ready behavior;
invalid values and parameters;
equality, zero, tie, displacement, clamp, or reversal semantics;
SVG accessibility and fixture-derived values;
deterministic playground controls and reduced motion;
responsive reader and standalone rendering.

None of those checks estimates future returns. A strategy study would still need point-in-time constituents, execution clocks, fees, slippage, survivorship controls, and out-of-sample evaluation.

Historical-example decision

A named historical chart is not useful for this mechanism lesson. It would introduce vendor data, adjustment, identifier, session, licensing, and hindsight ambiguity without strengthening the arithmetic. The synthetic paths isolate the causal rule and can be redistributed with the package.

Common questions

Is Supertrend a prediction?

No. It is a deterministic transformation of observed bars under the selected convention.

Can I compare values across platforms?

Only after aligning the source field, price basis, windows, seed, boundary rules, and display displacement.

What should I log in production?

Log the parameters, first-ready index, current intermediate state, input revision identifier, and the exact convention version.

What is the next tutorial?

Continue to Relative Strength Index, which changes the trend-system question and makes a different state or normalization visible.

Workflows

Rendered from the canonical Mermaid sources linked by this article.

Supertrend calculation flow

Rendering system map…

Takeaway: the displayed line is reproducible only when the hidden state and its boundary convention are preserved.

References5 primary sources and evidence notes

Expand the source trail, evidence role, and limitations behind the engineering choices.

Access date for web sources: 2026-07-26. Public artifacts use only deterministic synthetic data.

R1 — Olivier Seban's Supertrend

Organization or authors: Olivier Seban's Supertrend
Source type: Original or origin-attribution publication record
Publication or effective date: See catalog record
Version: Bibliographic record accessed 2026-07-26
URL or DOI: https://www.tradingview.com/support/solutions/43000634738-supertrend/
Accessed: 2026-07-26
Jurisdiction: General technical analysis; no regulatory jurisdiction
Evidence role: Origin and historical-definition context
Supports: Authorship/origin and the conceptual purpose of the method.
Limitations: The public record does not by itself freeze every modern platform seed, tie, plotting, or rounding convention.
Publication decision: Cite for origin; use maintained documentation and the package contract for executable semantics.

R2 — TradingView Supertrend

Organization or authors: TA-Lib project or TradingView, as identified by the linked page
Source type: Maintained official technical documentation
Publication or effective date: Current page
Version: Page accessed 2026-07-26
URL or DOI: https://www.tradingview.com/support/solutions/43000634738-supertrend/
Accessed: 2026-07-26
Jurisdiction: General technical analysis; platform applicability stated in the package
Evidence role: Formula and maintained implementation-context evidence
Supports: Supertrend builds basic ATR bands around the bar midpoint, ratchets them with previous-band rules, and activates one band according to a recursive direction state.
Limitations: Documentation cannot establish predictive power, profitability, or universal platform parity.
Publication decision: Publish formula facts with the package's selected conventions visibly separated.

R3 — TA-Lib ATR

Organization or authors: TA-Lib project or TradingView
Source type: Pinned maintained source or maintained calculation guide
Publication or effective date: Repository commit or current guide
Version: Page accessed 2026-07-26
URL or DOI: https://ta-lib.org/functions/atr
Accessed: 2026-07-26
Jurisdiction: General technical analysis
Evidence role: Executable or platform-convention evidence
Supports: True range and Wilder ATR used as the volatility input to the package Supertrend convention.
Limitations: TA-Lib does not define Supertrend itself.
Publication decision: Use to regression-check semantics; document intentional differences instead of implying universal equivalence.

R4 — Canonical synthetic fixture and independent arithmetic

Organization or authors: The Fintech Builder
Source type: Author-derived calculation from synthetic teaching inputs
Publication or effective date: 2026-07-26
Version: Fixture schema 2.0
URL or DOI: datasets/supertrend-fixtures.json
Accessed: 2026-07-26
Jurisdiction: Not applicable
Evidence role: Reproducibility and Python/TypeScript parity
Supports: Published worked values, warm-up, equality, reset, and scenario behavior.
Limitations: Synthetic observations prove calculation behavior only; they are not market evidence.
Publication decision: Redistributable with the package; label every use synthetic.

R5 â€” TradingView Pine Script built-ins documentation

Organization or authors: TA-Lib project or TradingView
Source type: Maintained official technical documentation
Publication or effective date: Current page
Version: Page accessed 2026-07-26
URL or DOI: https://www.tradingview.com/pine-script-docs/language/built-ins/
Accessed: 2026-07-26
Jurisdiction: General technical analysis; platform applicability stated in the package
Evidence role: Neighboring-function and platform-reconciliation evidence
Supports: Maintained ta.supertrend platform context and version boundary.
Limitations: A maintained platform record documents its own convention and does not make the package convention universal.
Publication decision: Use in the reconciliation matrix; retain package choices and intentional differences explicitly.

Implementation

Full dependency-light reference implementations in both supported languages.

supertrend.ts

export type Numeric = number | null;

    function validateSeries(values: number[], name: string): void {
      if (!Array.isArray(values) || values.length === 0) throw new RangeError(`${name} must be a non-empty array`);
      if (values.some((value) => typeof value !== "number" || !Number.isFinite(value))) {
throw new TypeError(`${name} must contain only finite numbers`);
      }
    }

    function validateHL(high: number[], low: number[]): void {
      validateSeries(high, "high");
      validateSeries(low, "low");
      if (high.length !== low.length) throw new RangeError("high and low lengths must match");
      if (high.some((value, index) => value < low[index])) throw new RangeError("high must be >= low");
    }

    function validateHLC(high: number[], low: number[], close: number[]): void {
      validateHL(high, low);
      validateSeries(close, "close");
      if (close.length !== high.length) throw new RangeError("high, low, and close lengths must match");
      if (close.some((value, index) => value < low[index] || value > high[index])) {
throw new RangeError("close must lie inside each high-low range");
      }
    }
export function supertrend(high: number[], low: number[], close: number[], period = 10, multiplier = 3) {
  validateHLC(high, low, close);
  if (!Number.isInteger(period) || period < 1) throw new RangeError("period must be a positive integer");
  if (!Number.isFinite(multiplier) || multiplier <= 0) throw new RangeError("multiplier must be finite and positive");
  const size = high.length;
  const true_range: Numeric[] = high.map((value, index) => index === 0 ? value - low[index] : Math.max(value - low[index], Math.abs(value - close[index - 1]), Math.abs(low[index] - close[index - 1])));
  const atr: Numeric[] = Array(size).fill(null);
  const basic_upper: Numeric[] = Array(size).fill(null);
  const basic_lower: Numeric[] = Array(size).fill(null);
  const final_upper: Numeric[] = Array(size).fill(null);
  const final_lower: Numeric[] = Array(size).fill(null);
  const line: Numeric[] = Array(size).fill(null);
  const direction: Array<string | null> = Array(size).fill(null);
  const reversal: Array<boolean | null> = Array(size).fill(null);
  if (size >= period) {
    const seedIndex = period - 1;
    let atrValue = true_range.slice(0, period).reduce<number>((sum, value) => sum + (value as number), 0) / period;
    for (let index = seedIndex; index < size; index += 1) {
      if (index > seedIndex) atrValue = (atrValue * (period - 1) + (true_range[index] as number)) / period;
      atr[index] = atrValue;
      const midpoint = (high[index] + low[index]) / 2;
      basic_upper[index] = midpoint + multiplier * atrValue; basic_lower[index] = midpoint - multiplier * atrValue;
      if (index === seedIndex) {
        final_upper[index] = basic_upper[index]; final_lower[index] = basic_lower[index];
        direction[index] = "down"; line[index] = final_upper[index]; reversal[index] = false; continue;
      }
      const previousUpper = final_upper[index - 1] as number;
      const previousLower = final_lower[index - 1] as number;
      final_upper[index] = (basic_upper[index] as number) < previousUpper || close[index - 1] > previousUpper ? basic_upper[index] : previousUpper;
      final_lower[index] = (basic_lower[index] as number) > previousLower || close[index - 1] < previousLower ? basic_lower[index] : previousLower;
      const previousDirection = direction[index - 1] as string;
      direction[index] = line[index - 1] === previousUpper ? (close[index] > (final_upper[index] as number) ? "up" : "down") : (close[index] < (final_lower[index] as number) ? "down" : "up");
      line[index] = direction[index] === "up" ? final_lower[index] : final_upper[index];
      reversal[index] = direction[index] !== previousDirection;
    }
  }
  return { true_range, atr, basic_upper, basic_lower, final_upper, final_lower, supertrend: line, direction, reversal };
}

Playground

The embedded lab now expands to its full document height, keeping the article as the only scroll surface.

Full-height labsupertrend labOpen full screen