Skip to main content

Legend

The legend is the value-and-identity layer rendered over the chart panes: OHLCV values, the symbol identity row, quote fields, indicator rows with their own controls, and custom market-status sections. Every one of those regions is configurable at runtime through LegendSettings, and every one has a defined appearance when its underlying value is missing.

Anatomy​

TradeScript legend region showing the OHLCV values row with time, the Bitcoin TetherUS symbol identity row with logo and exchange, a drawing favorites shortcut row, and an EMA indicator row with hide, settings, and remove controls

BTCUSDT · 15m · dark theme — legend region captured from the live playground.

Four rows stack from the top of the pane:

  1. Values row — Open / High / Low / Close / Volume / Time for the bar selected by LegendSettings.valueSource (crosshair bar, latest loaded bar, or rightmost visible bar). Visibility: showValues.
  2. Symbol identity row — symbol logo (showSymbolLogo), title from symbolTitleSource, exchange, and interval. Editable affordances come from editableSymbol and editableInterval.
  3. Drawing favorites row — the starred drawing shortcuts under the identity row. This row is drawing chrome, not a legend row; its placement is ChartDisplaySettings.favoritesToolbar.
  4. Indicator row — EMA(5,10,20,30,60,120,close) with hide, settings, and remove buttons plus per-output value chips. Controlled by showIndicatorRows and the button toggles below.

Interactions​

  • Clicking the symbol or interval (when editableSymbol / editableInterval are on) opens symbol search or the interval picker.
  • When showContextMenu is enabled, symbol and indicator legend rows expose a dedicated row context menu.
  • showLegendButtons hides all inline legend buttons, while showHideButton, showSettingsButton, and showDeleteButton suppress those icons independently without changing the underlying native chart APIs.
  • Hiding a button removes the affordance, not the capability. The corresponding chart API stays callable from host code.

Value formatting​

  • valueSource selects whether no-crosshair legend values use the latest loaded bar or the rightmost visible bar; with a crosshair active, values track the crosshair bar.
  • unavailableValueLabel controls unavailable candle and indicator legend value text — never show stale values as current.
  • The volume quote field uses the active chart locale for compact number formatting, and quote timestamp fields use the active chart locale and timezone.
  • Change and change-percent quote fields use signed value colors by default; set LegendSettings.changeValueColoring: 'none' to render them with the default legend text color.
  • Use LegendSettings.backgroundVisible, backgroundColor, and backgroundOpacity for the boxed main-series legend background.

Series and indicator states​

RegionSourceLoading or unavailable behavior
Symbol title/logoResolved SymbolInfoKeep a text identity when a logo is absent
OHLCV rowCrosshair bar, latest bar, or rightmost visible bar per valueSourceUse unavailableValueLabel; never show stale values as current
Quote fieldsgetQuotes / subscribeQuotesHide or mark unavailable fields according to settings
Indicator rowsIndicator outputs and metadataHide null rows only when explicitly configured
Market statusSession/data status plus host status sectionsShow the documented fallback when schedule data is missing

Per-state controls:

  • hideUnavailableIndicatorValues omits indicator legend rows whose current output is null or undefined.
  • showValuesOnMobile keeps candle legend values visible on compact/mobile layouts even if desktop value rows are hidden.
  • showIndicatorTitles: false hides indicator names; showIndicatorValues: false hides indicator output rows.
  • showBooleanIndicatorArguments: false omits boolean values from indicator argument text; showIndicatorInputValues: false hides indicator input values from legend argument text.
  • hideMainSeriesSymbolFromIndicatorLegend: true omits symbol input values when they match the active chart symbol.
  • showDataStatusInLegend renders delayed, end-of-day, or offline data status from SymbolInfo.dataStatus.

Quote fields and market status​

  • Known quote fields include last, bid, ask, spread, OHLC values, previous close, volume, extended-hours values, quote status, and timestamps.
  • Unknown field names are read from Quote.metadata, so hosts can add venue-specific legend chips without changing SDK code.
  • Use LegendSettings.showQuoteFields and quoteFields for explicit main-series fields such as volume, change, and changePercent.
  • showLastDayChange includes previous-day change and percent-change values in the main-series legend even when broader quote fields are hidden.
  • showPriceSourceInLegend includes the active SymbolInfo.priceSourceId / priceSources label in main-series and comparison legend labels.
  • showComparisonSymbolLogo renders comparison-series legend logos from SymbolInfo.logoUrls / logoUrl.
  • Market status sections render compact chips and can open a host-defined popup with details and action buttons. Their status field accepts built-in market states or host-defined status ids, so venues can surface states such as auctions, halts, volatility pauses, or data-quality modes without waiting for an SDK enum update.

Customization​

  • LegendSettings is the single control surface. It governs overall visibility, the symbol logo and title rows, the editable symbol and interval affordances, the inline buttons, the value rows and their mobile policy, the indicator rows, the quote fields, and which bar supplies values when no crosshair is active.
  • symbolTitleSource can use ticker, name, description, long-description, ticker-and-description, or ticker-and-long-description, so feeds can surface long exchange descriptions without host string rewriting.
  • Runtime API: chart.customization().setLegend(settings).
  • Symbol metadata and market status come from SymbolInfo, session schedules, quote data, and data status.
chart.customization().setLegend({
  visible: true,
  editableSymbol: true,
  editableInterval: true,
  showSymbolLogo: true,
  showComparisonSymbolLogo: true,
  showSymbolTitle: true,
  symbolTitleSource: 'ticker-and-description',
  showContextMenu: true,
  showLegendButtons: true,
  showHideButton: true,
  showSettingsButton: true,
  showDeleteButton: true,
  showValues: true,
  showValuesOnMobile: true,
  unavailableValueLabel: 'N/A',
  hideUnavailableIndicatorValues: true,
  showBooleanIndicatorArguments: false,
  showIndicatorRows: true,
  showQuoteFields: true,
  showLastDayChange: true,
  showPriceSourceInLegend: true,
  showDataStatusInLegend: true,
  quoteFields: ['last', 'bid', 'ask', 'spread', 'changePercent', 'extendedLast', 'extendedChangePercent', 'volume', 'venue'],
  valueSource: 'last-visible',
  showMarketStatus: true,
  statusSections: [
    {
      id: 'venue',
      label: 'NYSE',
      status: 'auction-imbalance',
      value: 'Auction imbalance',
      color: '#38bdf8',
      icon: 'clock',
      tooltip: 'Opening auction imbalance',
      details: [{ label: 'Imbalance', value: '1.2M buy' }],
      action: { label: 'Session details', actionId: 'open-session-details' },
    },
  ],
});

Rendered rows​

  • The floating SDK legend row renders the symbol logo/title chip, comparison symbol logos when enabled, configured quote fields, and custom market-status sections.
  • Main-pane indicator rows render over the chart pane with hide/show, settings, code-edit, remove, and value chips when enabled.
  • Subpane indicator headers render hide/show, settings, code-edit, auto-fit, collapse/expand, remove, provider status, and value chips.
  • The period bar remains the primary symbol/interval control. The data window remains the dense inspection surface for OHLC/indicator values.