Session Info

Session UI formats feed-owned venue state and the next transition without changing absolute market timestamps.

Session info answers "what session is this symbol in right now" — regular hours, pre-market, after-hours, custom venue phases, closed, holiday, or halted — plus the upcoming session windows. It powers the SessionMetaBadge widget and is available through the market-data controller for custom UI. Behavior comes first below — the data's origin, its display and refresh, and what happens when the timezone shifts or the capability is missing — then the interfaces behind it.

Where the data comes from

The data comes from two optional feed methods:

• resolveSessionInfo(request) — one SessionInfo snapshot for a symbol.
• subscribeSessionInfo(subscription, callback) — pushes updated snapshots when the session state changes.

Feeds advertise support via supportsSessionInfo in MarketDataFeedConfig. If your feed declares a session schedule, createSessionInfoProvider(spec) implements resolveSessionInfo for free — the schedule compiler turns declared trading hours into concrete windows.

As a concrete example, a feed with this schedule:

const usEquities: SessionScheduleSpec = {
  timezone: 'America/New_York',
  week: [{
    days: [1, 2, 3, 4, 5],
    windows: [
      { open: '04:00', close: '09:30', state: 'pre-market' },
      { open: '09:30', close: '16:00' },                      // 'regular'
      { open: '16:00', close: '20:00', state: 'post-market' },
    ],
  }],
};

produces, at 08:30 New York time on a weekday, currentState: 'pre-market' with upcoming containing the 09:30–16:00 regular window — which the badge renders as the pre-market tone with a countdown to 09:30.

How states are displayed

SessionState is native state, not a fixed exchange-hours enum. Built-ins cover closed, pre-market, regular, post-market, holiday, and halted; feeds may also emit custom ids such as opening-auction, cash-morning, night, or closing-cross.

The badge conveys state by tone and exposes it for styling and tests via the data-session-state attribute:

currentState from the feed	Badge tone	Countdown
regular	Green (open)	To the current window's close
pre-market / post-market	Blue / violet	To the next transition
Custom active id (e.g. opening-auction)	Amber, label derived from the id (Opening Auction)	Same treatment as built-in active windows
halted	Red	—
closed / holiday	Muted	To the next upcoming open
Capability missing	Unavailable label	—

Refresh behavior

The badge resolves once via resolveSessionInfo, then applies every snapshot pushed through subscribeSessionInfo. Between snapshots it ticks the countdown locally (countdownIntervalMs, default 1000 ms) against the upcoming window bounds; no polling of the feed is involved. When the symbol prop changes, the badge unsubscribes and resubscribes for the new symbol.

Timezones

All SessionInfo timestamps (asOf, opensAt, closesAt) are absolute Unix milliseconds. SessionInfo.timezone is the exchange zone the windows were compiled in; the badge's clock and weekday labels are formatted with the active locale. Display timezone questions belong to Timezones — session math never depends on the viewer's browser zone.

When session info is unavailable

When the feed reports no session capability (supportsSessionInfo absent or false), the badge renders its unavailable label instead of guessing, and the market-data controller throws a capability SdkError when the method is missing. Hosts building custom UI should branch on capability before rendering session-dependent chrome.

Custom-session behavior

Custom active states are first-class: the badge renders a readable label derived from the id and applies the same countdown treatment as built-in active windows. Downstream surfaces (session shading, filtering) key off the same ids — see Session Schedules for declaring them.

SessionMetaBadge

A compact status badge with a live countdown to the next session transition:

import { SessionMetaBadge } from '@tradescript/pro/react/widgets/session-meta';

<SessionMetaBadge sdk={sdk} controller={marketData} symbol={symbol} />

Props:

• controller — a MarketDataControllerApi (from widget.data() or new MarketDataController(feed))
• symbol — the symbol to track; the badge resubscribes when it changes
• compact — hide the countdown, show only the state
• countdownIntervalMs — countdown tick rate, default 1000
• locale and translate — use the same localization resolver shape as the chart for badge text, popover copy, weekday labels, and clock text
• labels — final per-widget override for any display string (Partial<SessionMetaBadgeLabels>); defaults exported as DEFAULT_SESSION_META_LABELS
• now — injectable clock for deterministic tests

When rendered inside the TradeScript chart, the badge receives the chart's active LocalizationSettings. Standalone hosts can pass locale / translate directly, then use labels only for per-instance wording that should not live in the shared catalog.

SessionInfo interface

export interface SessionInfo {
  symbol: SymbolInfo;
  timezone: string;
  currentState: SessionState; // built-in state or feed-owned custom id
  asOf: number;
  upcoming: readonly SessionWindow[]; // { opensAt, closesAt, state } within the provider horizon
  note?: string;
}

Controller API

Outside React, the MarketDataController exposes the same surface:

const info = await marketData.resolveSessionInfo({ symbol });
const stop = marketData.subscribeSessionInfo({ symbol }, (next) => { /* ... */ });

Related pages

• Session Filtering — hide pre/post-market bars and drive the regular/extended toggle.
• Session Schedules — declare trading hours, holidays, and half-days once, in exchange-local time.