SciChart.js JavaScript 2D Charts API > Annotations API > NativeTextAnnotation
NativeTextAnnotation

 NativeTextAnnotation works almost exactly like the normal TextAnnotation but draws using the native text api that is new in SciChart.JS v3.  This allows for some significant benefits:

  • Performance - you can draw hundreds or even thousands of text labels without significant slowdown.
  • Multi-line text is much easier.  Separate lines with the newline (/n) character, and adjust lineSpacing and multiLineAlignment if needed.
  • Rotated text is much easier.  If you try and rotate svg text, you will often find it gets clipped by its own viewbox.  NativeText does not.  You can control the center of rotation if need be.
  • Text wrapping is much easier.  NativeTextAnnotation can wrap to the chart area, or to the width you set for it.  If you make the annotation editable you can see the wrapping change as you resize.
  • Scale property allows text to be drawn at different sizes without creating a new font.

There are also some limitations compared to svg text:

  • Font style and font weight are not supported.  Fonts other than Arial must be ttf and either be hosted on your server or registered if coming from the internet.  See Native Text Font Loading

 The example below demonstrates the various features of NativeTextAnnotation.

import {
          SciChartSurface ,
          NumericAxis ,
          NumberRange ,
          EWrapTo,
          NativeTextAnnotation,
          GenericAnimation 
} from "SciChart";
export async function nativeTextAnnotationExample(divElementId) {
    const { sciChartSurface, wasmContext } = await SciChartSurface.create(divElementId);
    sciChartSurface.xAxes.add(new NumericAxis(wasmContext, { visibleRange: new NumberRange(0, 10) }));
    sciChartSurface.yAxes.add(new NumericAxis(wasmContext, { visibleRange: new NumberRange(0, 10) }));
   
    const nativeText1 = new NativeTextAnnotation({
        x1: 1,
        y1: 9,
        text: "The default font is Arial, which does not need to be hosted or registered",
        fontSize: 18
     });
     sciChartSurface.annotations.add(nativeText1);
     await sciChartSurface.registerFont(
        "notoserif",
        "https://raw.githubusercontent.com/google/fonts/main/ofl/notoserif/NotoSerif-Regular.ttf"
    );
     const nativeText2 = new NativeTextAnnotation({
        x1: 3,
        y1: 7,
        text: "This text uses a font from the internet",
        fontFamily: "notoserif",
        fontSize: 24
     });
     sciChartSurface.annotations.add(nativeText2);
     const nativeText3 = new NativeTextAnnotation({
        x1: 1,
        y1: 5,
        text: "Native text supports\nmultiline and rotation",
        fontFamily: "arial",
        fontSize: 24,
        rotation: 30,
        textColor: "orange"
     });
     sciChartSurface.annotations.add(nativeText3);
     const nativeText4 = new NativeTextAnnotation({
        x1: 5,
        y1: 5,
        text: "Native text can automatically wrap to the chart area or the annotation width.  ",
        fontFamily: "arial",
        fontSize: 24,
        isEditable: true,
        wrapTo: EWrapTo.ViewRect
     });
     sciChartSurface.annotations.add(nativeText4);
     const nativeText5 = new NativeTextAnnotation({
        x1: 5,
        y1: 3,
        text: "Native text can be scaled\nwithout changing the font size",
        fontFamily: "arial",
        fontSize: 16,
     });
     sciChartSurface.annotations.add(nativeText5);
     const scaleAnimation = new GenericAnimation({
        from: 0,
        to: 1,
        duration: 2000,
        onAnimate: (from, to, progress) => {
            if (progress < 0.5) {
                nativeText5.scale = 1 + progress;
            } else {
                nativeText5.scale = 1 + (1 - progress);
            }
        },
        onCompleted: () => { scaleAnimation.reset() }
     });
     sciChartSurface.addAnimation(scaleAnimation);
}
import {SciChartSurface} from "scichart/Charting/Visuals/SciChartSurface";
import { chartBuilder } from "scichart/Builder/chartBuilder";
import { EWrapTo } from "scichart/Charting/Visuals/Annotations/NativeTextAnnotation";
import { GenericAnimation } from "scichart/Core/Animations/GenericAnimation";
import { EAnnotationType } from "scichart/Charting/Visuals/Annotations/IAnnotation";
export async function nativeTextAnnotationBuilderAPIExample(divElementId) {
    const { sciChartSurface, wasmContext } = await chartBuilder.buildChart(divElementId, {
        annotations: [
            { type: EAnnotationType.RenderContextNativeTextAnnotation, options: {
                x1: 1,
                y1: 9,
                text: "The default font is Arial, which does not need to be hosted or registered",
                fontSize: 18
            }},
            { type: EAnnotationType.RenderContextNativeTextAnnotation, options: {
                x1: 3,
                y1: 7,
                text: "This text uses a font from the internet",
                fontFamily: "notoserif",
                fontSize: 24
            }},
            { type: EAnnotationType.RenderContextNativeTextAnnotation, options: {
                x1: 1,
                y1: 5,
                text: "Native text supports\nmultiline and rotation",
                fontFamily: "arial",
                fontSize: 24,
                rotation: 30,
                textColor: "orange"
             }},
             { type: EAnnotationType.RenderContextNativeTextAnnotation, options: {
                x1: 5,
                y1: 5,
                text: "Native text can automatically wrap to the chart area or the annotation width.  ",
                fontFamily: "arial",
                fontSize: 24,
                isEditable: true,
                wrapTo: EWrapTo.ViewRect
             }},
             { type: EAnnotationType.RenderContextNativeTextAnnotation, options: {
                id: "scaleAnnotation",
                x1: 5,
                y1: 3,
                text: "Native text can be scaled\nwithout changing the font size",
                fontFamily: "arial",
                fontSize: 16,
             }}
        ]
    });
    // This only needs to be done once in the application.  The font is cached locally.
    // It does not even need to be done before the font is used.  SciChart will redraw until the font is available.
    await sciChartSurface.registerFont(
        "notoserif",
        "https://raw.githubusercontent.com/google/fonts/main/ofl/notoserif/NotoSerif-Regular.ttf"
    );
    const scaleAnnotation = sciChartSurface.annotations.getById("scaleAnnotation");
    const scaleAnimation = new GenericAnimation({
        from: 0,
        to: 1,
        duration: 2000,
        onAnimate: (from, to, progress) => {
            if (progress < 0.5) {
                scaleAnnotation.scale = 1 + progress;
            } else {
                scaleAnnotation.scale = 1 + (1 - progress);
            }
        },
        onCompleted: () => { scaleAnimation.reset() }
     });
     sciChartSurface.addAnimation(scaleAnimation);
}

 

See Also

Miscellaneous APIs

DataLabels API