Options
All
  • Public
  • Public/Protected
  • All
Menu

Class SmartDateLabelProvider

Go to JavaScript Charting Documentation
Go to JavaScript Chart Examples
Go to SciChart.js on Github

The SmartDateLabelProvider formats Axis Labels and Cursor / Tooltips for NumericAxis types

Hierarchy

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Properties

alwaysShowFirstLabel

alwaysShowFirstLabel: boolean = false

Whether to show the leftmost (or rightmost on axes with flippedCoordinates) label as long as its tick line is visible.

If true and the label width is wider than the difference between majorTicks, it will prefer to push/hide the 2nd label instead of disappearing itself, as long as its tick-line is still in view.

Valuable when used inside of a SmartDateLabelProvider, paired with its showWiderDateOnFirstLabel: true.

Default false for all label providers, except for SmartDateLabelProvider.

Protected firstLabel

firstLabel: boolean = true

format

format: ETradeChartLabelFormat | string | undefined

The time range used to determine the current formating style

Protected formatCursorLabelProperty

formatCursorLabelProperty: TFormatLabelFn

Protected formatLabelProperty

formatLabelProperty: TFormatLabelFn

parentAxis

parentAxis: AxisCore

The parent AxisCore. This will be set once attachedToAxis is called

Protected providerId

providerId: string = generateGuid()

Protected styleId

styleId: string

This is the id for the text style used by this axis, as stored in the label cache. Cached labels are accessed by text and styleId. If you have useSharedCache = true and are overriding getLabelTexture or getLabelTextureAsync and do not ensure the style is unique, you might not get the labels you expect. You can either set useSharedCache = false, set this to some unique value, or override getCachedStyle

textVariesForSameTick

textVariesForSameTick: boolean = true

Protected tickToText

tickToText: Map<number, string> = new Map<number, string>()

Readonly type

type: SmartDate = ELabelProviderType.SmartDate

useCache

useCache: boolean = !IS_TEST_ENV

Used internally only for testing

useNativeText

useNativeText: boolean

Whether to use WebGL for rendering axis labels. Default true (was false before v4). These are much faster than rendering using canvas text, but do not have quite the same font and style support.

Set SciChartDefaults.useNativeText to change the global default.

useSharedCache

useSharedCache: boolean

Whether to use cached labels from other axes that have the same style. You may need to set this false if you are overriding getLabelTexture without setting a unique style. Can be set globally using SciChartDefaults. Currently default false.

Accessors

cursorNumericFormat

cursorPrecision

  • get cursorPrecision(): number
  • set cursorPrecision(value: number): void

  • Gets or sets the precision to use for cursors labels

    Returns number

  • Gets or sets the precision to use for cursors labels

    Parameters

    • value: number

    Returns void

dateOffset

  • get dateOffset(): number
  • set dateOffset(value: number): void

  • A timestamp in seconds to add to the value being formatted.

    Returns number

  • A timestamp in seconds to add to the value being formatted.

    Parameters

    • value: number

    Returns void

datePrecision

  • Gets or sets the precision of the input data values. Defaults to EDatePrecision.Seconds (Unix).

    Returns EDatePrecision

  • Gets or sets the precision of the input data values. Defaults to EDatePrecision.Seconds (Unix).

    Parameters

    Returns void

formatCursorLabel

  • Gets or sets a formatCursorLabel function which is used for formatting a data-value into a string for display on a cursor or tooltip If you are creating a custom LabelProvider, you should override formatCursorLabelProperty, not the formatCursorLabel property! See our Documentation

    Returns TFormatLabelFn

  • Gets or sets a formatCursorLabel function which is used for formatting a data-value into a string for display on a cursor or tooltip If you are creating a custom LabelProvider, you should override formatCursorLabelProperty, not the formatCursorLabel property! See our Documentation

    Parameters

    Returns void

formatLabel

  • Gets or sets a formatLabel function which is used for formatting a data-value into a string for display on the axis labels. If you are creating a custom LabelProvider, you should override formatLabelProperty, not the formatLabel property! See our Documentation

    Returns TFormatLabelFn

  • Gets or sets a formatLabel function which is used for formatting a data-value into a string for display on the axis labels. If you are creating a custom LabelProvider, you should override formatLabelProperty, not the formatLabel property! See our Documentation

    Parameters

    Returns void

highPrecisionLabelMode

  • Gets or Sets the high precision label mode. Default EHighPrecisionLabelMode.Suffix

    Returns EHighPrecisionLabelMode

  • Gets or Sets the high precision label mode. Default EHighPrecisionLabelMode.Suffix

    Parameters

    Returns void

labelThresholds

  • Gets or sets the custom label thresholds that map label formats to maximum time ranges. Allows you to customize when different label formats are used based on the visible time range. You can update individual thresholds by providing a partial object. Default DEFAULT_LABEL_THRESHOLDS.

    example
    // Override only the Minutes threshold
labelProvider.labelThresholds = {
    [ETradeChartLabelFormat.Minutes]: 60 * 60 * 24 * 7 // 7 days
};

    Returns {}

  • Gets or sets the custom label thresholds that map label formats to maximum time ranges. Allows you to customize when different label formats are used based on the visible time range. You can update individual thresholds by providing a partial object. Default DEFAULT_LABEL_THRESHOLDS.

    example
    // Override only the Minutes threshold
labelProvider.labelThresholds = {
    [ETradeChartLabelFormat.Minutes]: 60 * 60 * 24 * 7 // 7 days
};

    Parameters

    Returns void

lineSpacing

  • get lineSpacing(): number
  • set lineSpacing(value: number): void

  • Line spacing to use if text is wrapped, as a multiple of the text height. Defaults to 1.1

    Returns number

  • Line spacing to use if text is wrapped, as a multiple of the text height. Defaults to 1.1

    Parameters

    • value: number

    Returns void

numericFormat

postfix

  • get postfix(): string
  • set postfix(v: string): void

  • Gets or sets a string to add to the end of each label

    Returns string

  • Gets or sets a string to add to the end of each label

    Parameters

    • v: string

    Returns void

precision

  • get precision(): number
  • set precision(value: number): void

  • Gets or sets the precision to use when formatting

    Returns number

  • Gets or sets the precision to use when formatting

    Parameters

    • value: number

    Returns void

prefix

  • get prefix(): string
  • set prefix(v: string): void

  • Gets or sets a string to add to the beginning of each label

    Returns string

  • Gets or sets a string to add to the beginning of each label

    Parameters

    • v: string

    Returns void

rotation

  • get rotation(): number
  • set rotation(value: number): void

  • Returns number

  • Parameters

    • value: number

    Returns void

showSecondsOnPreciseDate

  • get showSecondsOnPreciseDate(): boolean
  • set showSecondsOnPreciseDate(value: boolean): void

  • Gets or Sets whether to show the seconds component on precise date formats.

    Returns boolean

  • Gets or Sets whether to show the seconds component on precise date formats.

    Parameters

    • value: boolean

    Returns void

showSecondsOnWideDate

  • get showSecondsOnWideDate(): boolean
  • set showSecondsOnWideDate(value: boolean): void

  • Gets or Sets whether to show the seconds component on wide date formats.

    Returns boolean

  • Gets or Sets whether to show the seconds component on wide date formats.

    Parameters

    • value: boolean

    Returns void

showWiderDateOnFirstLabel

  • get showWiderDateOnFirstLabel(): boolean
  • set showWiderDateOnFirstLabel(value: boolean): void

  • Returns boolean

  • Parameters

    • value: boolean

    Returns void

showYearOnWiderDate

  • get showYearOnWiderDate(): boolean
  • set showYearOnWiderDate(value: boolean): void

  • Gets or Sets whether the year should be shown in the wider format used on first label. Default false.

    Returns boolean

  • Gets or Sets whether the year should be shown in the wider format used on first label. Default false.

    Parameters

    • value: boolean

    Returns void

splitWideDateWithComma

  • get splitWideDateWithComma(): boolean
  • set splitWideDateWithComma(value: boolean): void

  • Gets or Sets whether your wide formatted dates have a comma in between date + month, and everything else

    Returns boolean

  • Gets or Sets whether your wide formatted dates have a comma in between date + month, and everything else

    Parameters

    • value: boolean

    Returns void

Methods

adjustLabel

  • adjustLabel(index: number, text: string, width: number, height: number, x: number, y: number, rx: number, ry: number, rotationRadians: number): { color: number; rotationRadians: number; rx: number; ry: number; text: string; x: number; y: number }

  • This method is called for each label just before drawing and can be used to make final adjustments to the label Note that if native text is NOT used, only x and y of the return values will be used. Only color can be returned undefined to use label default

    Parameters

    • index: number
    • text: string
    • width: number
    • height: number
    • x: number
    • y: number
    • rx: number
    • ry: number
    • rotationRadians: number

    Returns { color: number; rotationRadians: number; rx: number; ry: number; text: string; x: number; y: number }

    • color: number
    • rotationRadians: number
    • rx: number
    • ry: number
    • text: string
    • x: number
    • y: number

applyFormat

  • applyFormat(value: string): string

  • Parameters

    • value: string

    Returns string

attachedToAxis

Protected clearCache

  • clearCache(): void

convertToUnixSeconds

  • convertToUnixSeconds(value: number): number

  • Convert value from current precision (ticks) to standard Unix Seconds.

    note

    High precision values (nano) will lose precision here. Use only for coarse-grained logic (year / month / day checks).

    Parameters

    • value: number

    Returns number

delete

  • delete(): void

detachedFromAxis

  • detachedFromAxis(): void

Protected doFormat

  • doFormat(dataValue: number): string

  • This method is bound to the formatLabel method of the base labelProvider.

    Parameters

    • dataValue: number

    Returns string

formatDatePrecise

  • formatDatePrecise(labelRange: ETradeChartLabelFormat | string, valueInSeconds: number, rawValue?: number): string

  • Formats the value using the precise format for non-wide labels. The format depends on the highPrecisionLabelMode setting. This method can be overridden to customize precise label formatting.

    remarks

    For high precision formats (ns/µs/ms), the raw value is essential for maintaining precision. See EHighPrecisionLabelMode for more formatting details.

    remarks

    For coarser formats, only valueInSeconds is used.

    Parameters

    • labelRange: ETradeChartLabelFormat | string

      The label format range determined by the visible time span (e.g., Nanoseconds, Seconds, Days)

    • valueInSeconds: number

      The data value converted to Unix seconds with dateOffset already applied

    • Optional rawValue: number

      The original raw tick value, used to extract sub-second precision without floating point loss

    Returns string

    The formatted precise label string

formatDateWide

  • Formats the value in a wider format, used for the first label and when the formatted value changes (e.g., when crossing day/hour boundaries). This method can be overridden to customize wide label formatting.

    example

    // For high precision: "Jan 2, 2026 12:59:59" // For months: "Jan 2026" // For years: "2026"

    Parameters

    • labelRange: ETradeChartLabelFormat | string

      The label format range determined by the visible time span (e.g., Nanoseconds, Seconds, Days)

    • valueInSeconds: number

      The data value converted to Unix seconds with dateOffset already applied

    Returns string

    The formatted wide label string

Protected formatSmartLabel

  • formatSmartLabel(format: ETradeChartLabelFormat | string, valueInSeconds: number, prevValueInSeconds: number | undefined, prevPrevValueInSeconds: number | undefined, originalRawValue?: number): string

  • Main smart label formatting logic that determines when to display wide vs precise labels. This method can be overridden to customize the overall label selection strategy.

    remarks

    The method decides between wide and precise formats based on:

    1. Whether this is the first label (controlled by showWiderDateOnFirstLabel)
    2. Whether the wide-formatted value has changed from the previous label
    3. Special logic for month boundaries

    Wide labels provide date/time context (e.g., "1/1/2026 12:59:59"), while precise labels show incremental values (e.g., "00.000004000" or "4000ns").

    Parameters

    • format: ETradeChartLabelFormat | string

      The label format range (Nanoseconds, Microseconds, MilliSeconds, Seconds, Minutes, Days, Months)

    • valueInSeconds: number

      The current data value converted to Unix seconds with dateOffset applied

    • prevValueInSeconds: number | undefined

      The previous label's value in Unix seconds (undefined for first label)

    • prevPrevValueInSeconds: number | undefined

      The label before the previous one in Unix seconds (used for month formatting)

    • Optional originalRawValue: number

      The current raw tick value, preserving sub-second precision

    Returns string

    The formatted label string (either wide or precise format)

getCachedLabelTexture

  • Get a texture for the given label text. By default the textures are created first and then the resulting sizes are used by the layout functions

    Parameters

    • labelText: string

      The required text

    • textureManager: TextureManager

      A textureManager instance which contains methods for creating textures

    • labelStyle: TTextStyle

      The style for the text

    Returns TTextureObject

    A TTextureObject containing the bitmapTexture and the size

Protected getCachedStyle

  • This method creates the text style to be stored in the label cache. When useSharedCache = true, the label cache will generate a new styleId if this style does not match any existing style. Cached labels are accessed by text and styleId. If you are overriding getLabelTexture or getLabelTextureAsync and do not ensure the style is unique, you might not get the labels you expect. You can either set useSharedCache = false, override this and set the extras field in TCachedLabelStyle, or set styleId directly

    Returns TCachedLabelStyle

getLabelHeight

  • getLabelHeight(ctx: CanvasRenderingContext2D, labelText: string, labelStyle: TTextStyle): number

  • Called during axis layout to get the height of the label

    Parameters

    • ctx: CanvasRenderingContext2D

      the CanvasRenderingContext2D which can be used to perform text measurment

    • labelText: string

      the text of the label

    • labelStyle: TTextStyle

      the style of the label

    Returns number

    the label height in pixels

Protected getLabelRange

  • Return a range string, based on the numeric range of the axis. This will be used to choose which formatting to use. Uses the labelThresholds property to determine the appropriate format.

    Parameters

    • timeRangeSeconds: number
    • ticksNumber: number

    Returns ETradeChartLabelFormat | string

Protected getLabelSizesNative

  • getLabelSizesNative(labels: string[], textStyle: TTextStyle): void

getLabelTexture

  • getLabelTexture(labelText: string, textureManager: TextureManager, labelStyle: TTextStyle): { bitmapTexture: TSRTexture; textureHeight: number; textureWidth: number }

  • Create a texture for the given label text. This method is called if useNativeText is false. If overriding this method with useSharedCache = true, consider setting it false for this LabelProvider, otherwise other axes using the same style and text may see your custom texture. Alternatively you can override getCachedStyle or set styleId directly

    Parameters

    Returns { bitmapTexture: TSRTexture; textureHeight: number; textureWidth: number }

    • bitmapTexture: TSRTexture
    • textureHeight: number
    • textureWidth: number

getLabelTextureAsync

  • getLabelTextureAsync(labelText: string, textureManager: TextureManager, labelStyle: TTextStyle): Promise<{ bitmapTexture: TSRTexture; textureHeight: number; textureWidth: number }>
  • deprecated

    AsyncLabels have been removed. useNativeText: true provides much greater performance benefit. If using texture labels override getLabelTexture instead

    Parameters

    Returns Promise<{ bitmapTexture: TSRTexture; textureHeight: number; textureWidth: number }>

getLabelWidth

  • getLabelWidth(ctx: CanvasRenderingContext2D, labelText: string, labelStyle?: TTextStyle): number

  • Called during axis layout to get the width of the label

    Parameters

    • ctx: CanvasRenderingContext2D

      the CanvasRenderingContext2D which can be used to perform text measurment

    • labelText: string

      the text of the label

    • Optional labelStyle: TTextStyle

      the style of the label

    Returns number

    the label width in pixels

getLabels

  • getLabels(majorTicks: number[]): string[]
  • inheritdoc

    Parameters

    • majorTicks: number[]

    Returns string[]

getMaxLabelHeightForHorizontalAxis

  • getMaxLabelHeightForHorizontalAxis(majorTickLabels: string[], ctx: CanvasRenderingContext2D, labelStyle: TTextStyle): number

  • Called during axis layout to get the maximum height of labels on a horizontal axis. Normally this calls getLabelHeight for each label and returns the largest.

    Parameters

    • majorTickLabels: string[]

      an array of text labels

    • ctx: CanvasRenderingContext2D

      the CanvasRenderingContext2D which can be used to perform text measurment

    • labelStyle: TTextStyle

      the style of the labels

    Returns number

    the maximum label height in pixels

getMaxLabelWidthForVerticalAxis

  • getMaxLabelWidthForVerticalAxis(majorTickLabels: string[], ctx: CanvasRenderingContext2D, labelStyle: TTextStyle): number

  • Called during axis layout to get the maximum width of labels on a vertical axis. Normally this calls getLabelWidth for each label and returns the largest.

    Parameters

    • majorTickLabels: string[]

      an array of text labels

    • ctx: CanvasRenderingContext2D

      the CanvasRenderingContext2D which can be used to perform text measurment

    • labelStyle: TTextStyle

      the style of the labels

    Returns number

    the maximum label width in pixels

getNativeLabelInfo

  • getNativeLabelInfo(labelText: string): LabelInfo

invalidateCache

  • invalidateCache(): void

Protected invalidateParent

  • invalidateParent(): void

onBeginAxisDraw

  • onBeginAxisDraw(): void

Protected pruneTickTextCache

  • pruneTickTextCache(): void

resetCache

  • resetCache(): void

toJSON

  • toJSON(): { options: {}; type: string }

  • Returns { options: {}; type: string }

    • options: {}
    • type: string

Generated using TypeDoc