TPO
Configure the TPO (Time Price Opportunity) chart type, session presets, block intervals, market structure levels, volume profiles, and context menu actions.
The TPO (Time Price Opportunity) chart type builds one market profile per trading session overlaid on candles, adding a lettered block to each price row for every sub-period in which price traded at that level. Because TPO profiles are computed from standard OHLC candles, the chart type works with any data provider, including the providers bundled with Vela's open-source core.
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';
enableVelaPro();
const workspace = new VelaWorkspace('#chart', {
layout: false,
symbol: 'BTCUSDT',
timeframe: '30',
priceStyle: 'tpo',
live: true,
providers: { binance: () => new BinanceProvider() },
});Setting priceStyle: 'tpo' opens the chart directly in TPO mode; without it, users can switch to TPO from the Chart style menu. Call enableTpo() before creating a workspace to register TPO without enabling the rest of Vela Pro, or pass enableVelaPro({ tpo: false }) to disable it.
The same session profile is also available as an overlay indicator (Time Price Opportunity) for charts that remain on candlesticks or another chart type. See Built-in indicators.
Data requirements
Rather than aggregating the chart's active timeframe bars, the TPO engine fetches candles at the configured Block interval for each visible session (30-minute candles by default, or 5-minute, 15-minute, 1-hour, or 4-hour candles when changed by the user). Any provider that serves historical candles for those intervals over a requested time window supports TPO.
TPO loads the eight most recent sessions initially and fetches older sessions on demand as the user pans backward. On a live chart, the active forming session refreshes every 30 seconds, while base candlesticks continue rendering underneath at the chart's selected timeframe.
Coloring TPO blocks by volume, trades, or delta additionally reads footprint slices and therefore requires a provider implementing Footprint data (FootprintFeed). On candle-only providers, block coloring remains in time mode.
Sessions and trading hours
The Session (session) setting partitions time into Day (default), Week, or Month profiles. Day sessions can be scoped further with Trading hours (tradingHours):
| Trading hours preset | Session window |
|---|---|
| Full day | Follows the chart's active trading session (default) |
| Regular hours (RTH), Extended hours (ETH) | Uses the symbol's regular or extended market session regardless of the chart's session toggle |
| Pre-market, Market, Post-market | 09:00 to 13:30, 13:30 to 20:00, and 20:00 to 00:00 UTC |
| London, New York, Asian | 08:00 to 16:30, 13:00 to 22:00, and 00:00 to 09:00 UTC |
| Custom | Custom UTC window specified in Custom hours as two HHMM integers |
In Custom hours, 930 represents 09:30 UTC and 12 represents 12:00 UTC. Setting identical start and end values covers the full 24-hour day, while an end time earlier than the start time spans across midnight.
When the data provider supplies a market calendar for the symbol, Day, Week, and Month sessions align to exchange trading hours and respect market holidays. Without a market calendar, sessions anchor to UTC boundaries (midnight for days, Monday for weeks, and the 1st of the month for months). See Timeframes and sessions for provider session metadata.
Blocks and row sizing
Each block represents one sub-period of the session (30 minutes by default via Block interval). Periods are assigned sequential characters starting with A, B, … through uppercase letters, lowercase letters, and digits. Every price row touched during a period receives that period's block packed from the left, so the widest rows mark prices where the market spent the most time.
Row size (rowMode) controls vertical price bucketing, where Auto selects a tick step proportional to the session range and Manual uses Ticks per row (rowTicks, default 4). Period letters render inside blocks whenever rows are tall enough to display legible text. Blocks (showBlocks) and letters (showLetters) have independent toggles, allowing profiles to render solid blocks, letters only, or both.
Color row by (colorBy) determines how blocks are shaded:
| Option | Color mapping |
|---|---|
| Time (default) | Chronological gradient from the session open color to the session close color |
| Volume, Trades count | Four-step intensity scale reflecting activity per price row |
| Delta | Divergent buy-versus-sell dominance per price row |
Each coloring mode provides built-in palettes as well as a Custom option with configurable color swatches. When the user zooms out until sessions become too narrow for individual blocks, each profile collapses into a compact vertical summary bar spanning the session range.
Market structure levels
TPO computes key market profile levels per session and overlays them on the blocks:
| Structure level | Definition | Setting | Default |
|---|---|---|---|
| Point of control (POC) | Price row containing the highest number of TPO blocks | Point of control | On (true) |
| Value area (VAH / VAL) | Contiguous rows around the POC containing 70% of session blocks | Value area % | On (true), 70 |
| Initial balance (IB) | High-low price range established during the first 60 minutes of the session | Initial balance, IB minutes | On (true), 60 |
| Single prints | Interior rows containing only a single TPO block | Single prints | On (true) |
| Poor high, poor low | Session extreme high or low row containing two or more TPO blocks | Poor high / low | On (true) |
| Open and close | Directional markers at the session opening and closing prices | Open / close markers | On (true) |
| Midpoint | Midpoint of the session's overall high-low range | Midpoint | Off (false) |
Rows outside the value area render at reduced opacity (Outside VA opacity, default 45%). Three additional overlays are disabled by default: VA fill (vaFill) shades the background band between VAH and VAL, Extend POC until reached (pocExtend) projects the POC rightward until a later bar trades through that price, and level price labels print exact POC, VAH, and VAL prices alongside each session.
Session volume profile
Enabling Volume profile (volumeProfile, default false) draws a companion volume-by-price histogram alongside each session's TPO profile, computed from the chart's bars and split into up-bar and down-bar volume:
| Setting | Default | Description |
|---|---|---|
| Position | Right ('right') | Side of the session anchor from which the volume histogram extends |
| Rows | 24 | Number of vertical price buckets in the histogram |
| Width (%) | 30 | Maximum histogram width as a percentage of session width |
| Offset (bars) | 0 | Horizontal right offset (in bars) applied to the active forming session's histogram |
| Anchor to last bar | Off (false) | Anchors the forming session's histogram to the right of the newest bar |
| Volume POC | On (true) | Highlights the histogram row with the highest traded volume |
| Value area (%) | 70 | Percentage of session volume enclosed by the volume profile's value area |
The session volume profile provides independent POC, VAH, and VAL price labels separate from the TPO structure labels.
Context menu actions
Right-clicking directly on a TPO profile's blocks opens a profile-specific context menu, while right-clicking elsewhere opens the standard chart context menu:
| Menu item | Action |
|---|---|
| Expand TPO | Splits the profile horizontally so each period block aligns over the candle that produced it |
| Collapse TPO | Packs an expanded profile back against the left session boundary |
| Merge to previous TPO | Combines the clicked profile with the preceding session into a composite profile |
| Merge to following TPO | Combines the clicked profile with the following session (disabled on the active forming session) |
| Unmerge all TPOs | Restores a merged composite profile back into individual sessions |
| Unmerge TPO | Extracts a single session chosen from a submenu out of a merged profile |
| TPO Settings | Opens the Chart settings dialog on the TPO tab |
Hovering any TPO block displays a tooltip with its period letter, row price range, and block UTC time interval.
Programmatic configuration
The TPO tab in Chart settings organizes options under Sessions, Display, Structure, Volume profile, and Markers. Settings are stored under chartTypes.tpo in the renderer configuration and can be updated partially with renderer.applyConfig():
import type { VelaWorkspace } from '@luxalgo/vela/workspace';
declare const workspace: VelaWorkspace;
const renderer = workspace.chart.renderer;
renderer.applyConfig({
chartTypes: {
tpo: {
session: 'day',
tradingHours: 'london',
blockInterval: '60', // minutes as string: '5', '15', '30', '60', or '240'
vaPercent: 68,
volumeProfile: true,
},
},
});
renderer.openSettings('TPO'); // open Chart settings directly on the TPO tab| Config key | Accepted values | Default |
|---|---|---|
session | 'day', 'week', 'month' | 'day' |
tradingHours | 'full', 'regular', 'extended', 'premarket', 'market', 'postmarket', 'london', 'newyork', 'asia', 'custom' | 'full' |
customStart, customEnd | HHMM integers in UTC | 0 |
blockInterval | '5', '15', '30', '60', '240' | '30' |
rowMode, rowTicks | 'auto' or 'manual'; integer tick count | 'auto', 4 |
colorBy | 'time', 'volume', 'trades', 'delta' | 'time' |
showBlocks, showLetters | boolean | true |
valueArea, vaPercent, vaFill | boolean, percentage number, boolean | true, 70, false |
poc, pocExtend | boolean | true, false |
ib, ibMinutes | boolean, duration in minutes | true, 60 |
singles, poorExtremes | boolean | true |
openClose, midpoint | boolean | true, false |
volumeProfile, vpPosition, vpRows, vpWidth | boolean, 'right' | 'left', row count, width % | false, 'right', 24, 30 |
Profile merges and expansions performed through the context menu are stored in the same chartTypes.tpo object and persist automatically in the workspace state document. See Layouts and chart state.