Custom High Precision Date Labels

Demonstrates how to customize specific label formats on a High Precision Date Axis, using external libraries like date-fns.

src/drawExample.ts
import {
    DateTimeNumericAxis,
    EllipsePointMarker,
    MouseWheelZoomModifier,
    ZoomExtentsModifier,
    ZoomPanModifier,
    XyDataSeries,
    NumericAxis,
    FastLineRenderableSeries,
    SciChartSurface,
    EAutoRange,
    SmartDateLabelProvider,
    EResamplingMode,
    EDatePrecision,
    EHighPrecisionLabelMode,
    ETradeChartLabelFormat,
    NumberRange,
    NativeTextAnnotation,
    EHorizontalAnchorPoint,
    ECoordinateMode,
} from "scichart";
import { format, fromUnixTime } from "date-fns";

const toUTC = (date: Date) => {
    // SciChart internally uses UTC dates, so convert to UTC
    return new Date(date.valueOf() + date.getTimezoneOffset() * 60 * 1000);
};

export const drawExample = async (rootElement: string | HTMLDivElement) => {
    const { wasmContext, sciChartSurface } = await SciChartSurface.create(rootElement);

    const startDate = new Date("2025-01-01T00:00:00Z");
    const startTimeSeconds = startDate.getTime() / 1000;

    const xAxis = new DateTimeNumericAxis(wasmContext, {
        axisTitle: "Time",
        datePrecision: EDatePrecision.Nanoseconds, // Very important -> 1 x-value increment == 1 nanosecond
        highPrecisionLabelMode: EHighPrecisionLabelMode.Suffix,
        dateOffset: startTimeSeconds, // in seconds

        showWiderDateOnFirstLabel: true,
        showYearOnWiderDate: true,

        splitWideDateWithComma: false,

        showSecondsOnWideDate: true, // Usually these 2 should be opposites: when wide date shows seconds, precise date shouldn't.
        showSecondsOnPreciseDate: true,
    });
    sciChartSurface.xAxes.add(xAxis);

    const labelProvider = xAxis.labelProvider as SmartDateLabelProvider;

    // 1. Capture the original SciChart implementations
    const defaultFormatDateWide = labelProvider.formatDateWide.bind(labelProvider);
    const defaultFormatDatePrecise = labelProvider.formatDatePrecise.bind(labelProvider);

    // 2. Define the Custom "date-fns" implementations
    // Wide dates -> e.g. "Jan 01, 2025 12:00:00"
    const customFormatDateWide = (labelRange: ETradeChartLabelFormat | string, valueInSeconds: number) => {
        const date = toUTC(fromUnixTime(valueInSeconds));
        if (
            labelRange === ETradeChartLabelFormat.Nanoseconds ||
            labelRange === ETradeChartLabelFormat.Microseconds ||
            labelRange === ETradeChartLabelFormat.MilliSeconds
        ) {
            return format(date, "MMM dd, yyyy HH:mm:ss");
        } else if (labelRange === ETradeChartLabelFormat.Seconds || labelRange === ETradeChartLabelFormat.Minutes) {
            return format(date, "MMM dd, yyyy");
        } else if (labelRange === ETradeChartLabelFormat.Days) {
            return format(date, "MMM yyyy");
        } else {
            return format(date, "yyyy");
        }
    };

    // Precise dates -> e.g. "12:59:59" or "03s12345ns"
    const customFormatDatePrecise = (
        labelRange: ETradeChartLabelFormat | string,
        valueInSeconds: number,
        rawValue?: number
    ) => {
        const date = toUTC(fromUnixTime(valueInSeconds));

        // High precision logic
        if (
            labelRange === ETradeChartLabelFormat.Nanoseconds ||
            labelRange === ETradeChartLabelFormat.Microseconds ||
            labelRange === ETradeChartLabelFormat.MilliSeconds
        ) {
            const mode = labelProvider.highPrecisionLabelMode;

            if (mode === EHighPrecisionLabelMode.Suffix && rawValue !== undefined) {
                const tps = labelProvider.datePrecision;
                const wholeSeconds = Math.floor(rawValue / tps);
                const ticksWithinSecond = rawValue - wholeSeconds * tps;
                const subSecondOffset = ticksWithinSecond / tps;

                const seconds = date.getUTCSeconds();
                const secondsStr = seconds.toString().padStart(2, "0");

                if (labelRange === ETradeChartLabelFormat.Nanoseconds) {
                    const ns = Math.round(subSecondOffset * 1_000_000_000);
                    return `${secondsStr}:${ns}ns`;
                }
                if (labelRange === ETradeChartLabelFormat.Microseconds) {
                    const us = Math.round(subSecondOffset * 1_000_000);
                    return `${secondsStr}:${us}µs`;
                }
                const ms = Math.round(subSecondOffset * 1_000);
                return `${secondsStr}:${ms}ms`;
            }
            return format(date, "ss.SSS");
        }

        if (labelRange === ETradeChartLabelFormat.Seconds) return format(date, "HH:mm:ss");
        if (labelRange === ETradeChartLabelFormat.Minutes) return format(date, "HH:mm");
        if (labelRange === ETradeChartLabelFormat.Days || labelRange === ETradeChartLabelFormat.Months)
            return format(date, "dd");

        return format(date, "dd/MM/yy");
    };

    // 3. Logic to toggle between them
    const setUseDateFns = (useCustom: boolean) => {
        if (useCustom) {
            labelProvider.formatDateWide = customFormatDateWide;
            labelProvider.formatDatePrecise = customFormatDatePrecise;
        } else {
            labelProvider.formatDateWide = defaultFormatDateWide;
            labelProvider.formatDatePrecise = defaultFormatDatePrecise;
        }
        // Force redraw to apply changes to existing labels
        sciChartSurface.invalidateElement();
    };

    // Apply custom by default initially
    setUseDateFns(true);

    sciChartSurface.yAxes.add(
        new NumericAxis(wasmContext, {
            axisTitle: "Signal (mV)",
            autoRange: EAutoRange.Always,
            growBy: new NumberRange(0.1, 0.1),
        })
    );

    // Data Generation
    const xValues: number[] = [];
    const yValues: number[] = [];
    type Generator = (i: number) => number;

    const addCluster = (startOffsetNano: number, count: number, generator: Generator) => {
        for (let i = 0; i < count; i++) {
            const x = startOffsetNano + i * 10_000_000;
            const noise = (Math.random() - 0.5) * 0.05;
            const y = generator(i) + noise;

            xValues.push(x);
            yValues.push(y);
        }
    };

    const ONE_SEC = 1_000_000_000; // Because we use `datePrecision = Nanoseconds`
    const ONE_MIN = ONE_SEC * 60;

    // 1. Damped Ringing
    addCluster(0, 2000, (i) => Math.sin(i * 0.1) * Math.exp(-i * 0.002) * 2);

    // 2. Frequency Chirp
    addCluster(1 * ONE_MIN, 2000, (i) => {
        const freq = 0.01 + i * 0.00005;
        return Math.sin(i * freq);
    });

    // 3. Amplitude Modulated Packet
    addCluster(3 * ONE_MIN, 2000, (i) => {
        const carrier = Math.sin(i * 0.1);
        const envelope = Math.sin(i * 0.03); // Slow envelope
        return carrier * envelope * 1.5;
    });

    // 4. Noisy "Heartbeat"
    addCluster(4 * ONE_MIN, 2000, (i) => {
        // spike every 200 points
        if (i % 200 < 20) return 1.0 + Math.random();
        return Math.random() * 0.2;
    });

    const lineSeries = new FastLineRenderableSeries(wasmContext, {
        dataSeries: new XyDataSeries(wasmContext, {
            xValues,
            yValues,
            containsNaN: false,
            isSorted: true,
            dataSeriesName: "Sensor A",
        }),
        stroke: "#50C7E0",
        strokeThickness: 2,
        resamplingMode: EResamplingMode.None,
        pointMarker: new EllipsePointMarker(wasmContext, {
            width: 4,
            height: 4,
            fill: "#2e3a59",
            stroke: "#50C7E0",
            strokeThickness: 1,
        }),
    });
    lineSeries.rolloverModifierProps.tooltipLabelX = "X";
    sciChartSurface.renderableSeries.add(lineSeries);

    sciChartSurface.chartModifiers.add(new MouseWheelZoomModifier(), new ZoomExtentsModifier(), new ZoomPanModifier());
    sciChartSurface.zoomExtents();

    sciChartSurface.annotations.add(
        new NativeTextAnnotation({
            xCoordinateMode: ECoordinateMode.Relative,
            yCoordinateMode: ECoordinateMode.Relative,
            x1: 0.5,
            y1: 0.08,
            horizontalAnchorPoint: EHorizontalAnchorPoint.Center,
            text: `Zoom in & out while toggling the switch to see different axis label formats
            \nSee how you can also customize date formatting at lines 60, 80 in drawExample.ts!`,
            lineSpacing: 10,
            fontSize: 16,
            opacity: 0.7,
            textColor: "#FFFFFF",
        })
    );

    return {
        wasmContext,
        sciChartSurface,
        controls: { setUseDateFns },
    };
};

High-Precision DateTimeNumericAxis with Custom Label Formatting - in React

Overview

This example demonstrates how to use DateTimeNumericAxis with nanosecond-precision data and the built-in SmartDateLabelProvider, while safely overriding date formatting logic using date-fns.

It highlights how SciChart dynamically switches between wide and precise date labels as you zoom, and how you can fully customize that behavior without breaking cursor labels, tick calculations, or high-precision rendering.

Use the toggle above the chart to switch between SciChart’s default formatting and a custom date-fns implementation.

Key Concepts Demonstrated

DateTimeNumericAxis with Nanosecond Precision

The X-axis is configured with:

  • datePrecision = EDatePrecision.Nanoseconds
  • A fixed dateOffset (Unix seconds)

This allows raw X values to represent nanosecond ticks, while still displaying full calendar dates and times on the axis. Each increment of 1 on the X-axis equals 1 nanosecond, making this suitable for high-frequency sensor data, trading systems, or scientific signals.

SmartDateLabelProvider

The SmartDateLabelProvider automatically adapts label formats based on the visible time range:

  • Wide labels provide context (e.g. Jan 01, 2025 12:00:00)
  • Precise labels show incremental detail (e.g. 59s345ms, 123456ns)

As you zoom in and out, the provider dynamically switches between: Nanoseconds, Microseconds, Milliseconds, Seconds, Minutes, Days / Months.

This logic is driven by internal label thresholds and the current visible range.

Custom Formatting with date-fns

This demo overrides two key methods on the SmartDateLabelProvider:

  • formatDateWide
  • formatDatePrecise

Instead of replacing the entire label provider, the original SciChart implementations are preserved and can be restored instantly. This ensures:

  • Cursor and rollover labels remain correct
  • Tick spacing and delta calculations are unaffected
  • High-precision math stays intact

The toggle switches between:

  • Default SciChart formatting
  • Custom date-fns formatting for both wide and precise labels

This pattern is recommended when integrating third-party date libraries.

When to Use This Approach

Use DateTimeNumericAxis with SmartDateLabelProvider when:

  • You need sub-millisecond or nanosecond resolution
  • You want automatic, readable date formatting
  • You need full control over label appearance
  • Cursor and tooltip accuracy is critical

This pattern is ideal for high-frequency trading, telemetry, scientific measurement, and real-time monitoring applications.

Related Documentation: