Skip to main content

Time Zone

The Time Zone feature provides comprehensive timezone management capabilities for the financial charting library. This system enables users to display chart data in different timezones while maintaining internal UTC consistency.

Key Features​

  • Timezone selection (IANA timezone database)
  • Real-time timezone conversion
  • Crosshair and axis label timezone formatting
  • Exchange-specific timezone support
  • Daylight Saving Time (DST) awareness
  • Timezone offset calculation
  • Popular timezone presets
  • Region-based timezone grouping

Architecture / Behavior​

The timezone system follows a layered architecture:

  1. Core Layer: TimezoneManager singleton handles all conversions
  2. API Layer: ChartApi methods for timezone control
  3. UI Layer: Timezone selector in toolbar and settings
  4. Rendering Layer: AxisRenderer and Tooltip use timezone formatting

The timezone flow: UI → ChartApi → ChartStore → TimezoneManager → Native Intl API → Rendering.

API Usage​

Initialization​

The timezone feature is enabled by default in the chart configuration:

const chart = Chart.create(document.getElementById('container'), {
  // ... other options
  timezone: 'America/New_York', // Set default timezone
});

Methods​

ChartApi.setTimezone() - Set the chart timezone:

// Set to Eastern Time
chart.getApi().setTimezone('America/New_York');

// Set to Indian Standard Time
chart.getApi().setTimezone('Asia/Kolkata');

// Set to UTC
chart.getApi().setTimezone('Etc/UTC');

ChartApi.getTimezone() - Get the current chart timezone:

const currentTz = chart.getApi().getTimezone();
console.log(currentTz); // 'America/New_York'

ChartApi.getAvailableTimezones() - Get list of available timezones:

const timezones = chart.getApi().getAvailableTimezones();
console.log(timezones.length); // 50+ timezones

Configuration Options​

OptionTypeDefaultDescription
timezonestring'Etc/UTC'Default timezone for the chart
timezone_groupsbooleantrueEnable region-based timezone grouping
popular_timezonesbooleantrueShow popular timezones first

Events​

  • timezone:changed - Fired when timezone changes
    • Payload: { old: string, new: string, timestamp?: number }

Customization​

  • UI styling can be customized via CSS classes
  • Timezone formatting can be customized using format strings
  • Popular timezones can be customized in TIMEZONE_GROUPS
  • Custom timezone presets can be added to COMMON_TIMEZONES

Use Cases​

  • Displaying US market data in Asian timezone
  • Comparing trading sessions across different regions
  • Technical analysis during specific market hours
  • Building multi-exchange trading platforms
  • Creating timezone-aware alerts and notifications

Limitations​

  • Requires browser support for Intl.DateTimeFormat API
  • Some older browsers may have limited timezone support
  • Performance depends on timezone complexity
  • DST transitions require careful handling

✅ Supported​

  • Timezone selection and switching
  • Real-time timezone conversion
  • Crosshair and axis label formatting
  • Exchange-specific timezone support
  • DST awareness
  • Timezone offset calculation
  • Popular timezone presets
  • Region-based timezone grouping

❌ Not Supported​

  • Automatic timezone detection based on user location
  • Custom timezone creation (non-IANA)
  • Historical timezone data
  • Timezone transition animations

⚠️ Partial / External​

  • Browser compatibility requires polyfill for older browsers
  • Custom timezone formatting requires understanding of format tokens

Feature Classification​

Core Feature - Fundamental functionality required for basic chart operation

Dependencies​

  • Requires backend? No
  • Requires storage? No
  • Requires real-time data? No
  • Requires UI controls? Yes (timezone selector)

Missing Implementation Analysis​

The timezone functionality is fully implemented and production-ready. All core timezone capabilities are present in the codebase with proper DST handling and performance optimizations.

Consistency Validation​

The timezone API follows the same pattern as other API methods with consistent promise-based return values and error handling. Naming conventions are consistent with other features.

UI vs API Separation​

  • UI handles: Timezone selector dropdown, timezone display in toolbar
  • API exposes: setTimezone(), getTimezone(), getAvailableTimezones() methods
  • Must implement manually: Custom timezone formatting, custom timezone presets

User Flow​

  1. User selects timezone from dropdown
  2. ChartApi validates timezone
  3. ChartStore updates timezone state
  4. TimezoneManager calculates offset
  5. AxisRenderer and Tooltip update formatting
  6. Chart displays data in selected timezone

Integration with Existing Docs​

This feature should be linked from:

  • Charting section → Top Toolbar
  • API Reference → ChartApi
  • Configuration → Chart Configuration
  • Getting Started → Quick Start Guide