Annotations in .NET MAUI Chart

10 Jan 202520 minutes to read

SfCartesianChart provides annotation support that allows you to mark specific areas of interest in the chart area. This feature enables you to add text, images, and custom views using the following annotations.

  • Text annotation
  • Shape annotation
  • View annotation

Adding Annotations

To add annotations, create an instance of any type of annotation and add it to the Annotations collection. For example, the EllipseAnnotation can be added.

<chart:SfCartesianChart>
    <!-- Other chart elements go here -->
    ...
    <!-- Annotations section of the chart -->
    <chart:SfCartesianChart.Annotations>
        <!-- Ellipse annotation -->
        <chart:EllipseAnnotation 
            X1="2"  
            X2="4"  
            Y1="10" 
            Y2="15" 
            Text="Ellipse"/>        
    </chart:SfCartesianChart.Annotations>    
</chart:SfCartesianChart>
// Create a new SfCartesianChart instance
SfCartesianChart chart = new SfCartesianChart();
...
// Other chart elements go here
// Create a new EllipseAnnotation
var ellipse = new EllipseAnnotation()
{
    X1 = 2,  // Set the X-coordinate of the start point
    Y1 = 10, // Set the Y-coordinate of the start point
    X2 = 4,  // Set the X-coordinate of the end point
    Y2 = 15, // Set the Y-coordinate of the end point
    Text = "Ellipse" // Set the text to display with the annotation
};

// Add the ellipse annotation to the chart's Annotations collection
chart.Annotations.Add(ellipse);

// Set the chart as the content of the current view
this.Content = chart;

Annotations in MAUI Chart

Positioning the annotation

Annotations can be positioned in the plot area based on the X1 and Y1 properties. For shape annotations, specify the X2 and Y2 properties, if needed. The X and Y values can be specified using axis units or pixel units, which can be identified by the CoordinateUnit property, as shown in the following code snippet:

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>        
        <chart:RectangleAnnotation X1="0" Y1="100" X2="300" Y2="400" Text="Pixel value" CoordinateUnit="Pixel"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
// Create a new SfCartesianChart object
SfCartesianChart chart = new SfCartesianChart();     

// Other chart elements go here

// Create a new RectangleAnnotation object
var rectangle = new RectangleAnnotation()
{
    X1 = 0,
    Y1 = 100,
    X2 = 300,
    Y2 = 400,
    CoordinateUnit = ChartCoordinateUnit.Pixel,  // Set the coordinate unit to Pixel
    Text = "Pixel value"
};

// Add the rectangle annotation to the chart's Annotations collection
chart.Annotations.Add(rectangle);

// Set the Content of the current view to the chart
this.Content = chart;

Annotations in pixel value in MAUI Chart

Adding annotation for multiple axes

When there are multiple axes, annotations can be added to a particular axis using the XAxisName and YAxisName properties. This is demonstrated in the code snippet below:

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.YAxes>
        <chart:NumericalAxis Minimum="0" Maximum="1"/>
        <chart:NumericalAxis Name="YAxis" CrossesAt="{Static x:Double.MaxValue}"/>
    </chart:SfCartesianChart.YAxes>

    <chart:SfCartesianChart.Annotations>
        <chart:EllipseAnnotation X1="2" X2="4" Y1="10" Y2="15" Text="Ellipse" YAxisName="YAxis"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
// Create a new Cartesian chart
SfCartesianChart chart = new SfCartesianChart();

// Create and configure the first Y-axis
NumericalAxis yAxis1 = new NumericalAxis();
yAxis1.Minimum = 0;
yAxis1.Maximum = 1;
chart.YAxes.Add(yAxis1);

// Create and configure the second Y-axis
NumericalAxis yAxis2 = new NumericalAxis();
yAxis2.Name = "YAxis";
yAxis2.CrossesAt = double.MaxValue; // Position the axis at the far right
chart.YAxes.Add(yAxis2);

// Create an ellipse annotation
var ellipse = new EllipseAnnotation()
{
    X1 = 2, 
    Y1 = 10, 
    X2 = 4, 
    Y2 = 15, 
    Text = "Ellipse", 
    YAxisName = "YAxis" // Specify which Y-axis to use for positioning
};

// Add the ellipse annotation to the chart
chart.Annotations.Add(ellipse);

// Set the chart as the content of the current view
this.Content = chart;

Annotations in multiple axes in MAUI Chart

Text annotation

The TextAnnotation is used to add simple text at specific points in the chart area using the Text property.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:TextAnnotation X1="2" Y1="25" Text="Text Annotation"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
// Create a new instance of SfCartesianChart
SfCartesianChart chart = new SfCartesianChart();

// Other chart elements go here

// Create a new TextAnnotation object
var text = new TextAnnotation()
{
    X1 = 2, 
    Y1 = 25,
    Text = "Text Annotation"  // Set the text content of the annotation    
};

// Add the TextAnnotation to the chart's Annotations collection
chart.Annotations.Add(text);

// Set the chart as the content of the current view/page
this.Content = chart;

Text annotation in MAUI Chart

Text Customization

The TextAnnotation can be customized using the LabelStyle property. The LabelStyle property provides options to customize the font-family, font-size, font-attributes, and text color of axis labels. The following properties are used to customize the text:

  • TextColor - Gets or sets the text color of the label.
  • Background - Gets or sets the background color of the labels.
  • Margin - Gets or sets the margin of the label to customize the appearance of label.
  • FontFamily - Gets or sets the font family name for the label.
  • FontAttributes - Gets or sets the font style for the label.
  • FontSize - Gets or sets the font size for the label.
  • HorizontalTextAlignment - Gets or sets the horizontal alignment of the label.
  • VerticalTextAlignment - Gets or sets the vertical alignment of the label.

Shape annotation

The ShapeAnnotation allows you to add annotations in the form of shapes such as rectangles, ellipses, lines, horizontal lines, and vertical lines at specific areas of interest in the chart area.

The following APIs are commonly used in all ShapeAnnotation:

  • X2 - Gets or sets the X2 coordinate of the shape annotation.
  • Y2 - Gets or sets the Y2 coordinate of the shape annotation.
  • Fill - Gets or sets the background color of the shape annotation.
  • Stroke - Gets or sets the stroke color of the shape annotation.
  • StrokeWidth - Gets or sets the stroke width of the shape annotation.
  • StrokeDashArray - Gets or sets the stroke dash pattern of the shape annotation.
  • Text - Gets or sets the annotation text of the shape annotation.
  • LabelStyle - Gets or sets the style for customizing the annotation text of the shape annotation.

Rectangle annotation

The RectangleAnnotation is used to draw a rectangle or a square at specific points in the chart area.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:RectangleAnnotation X1="1" Y1="40" X2="2" Y2="20"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();

// Create a new rectangle annotation
var rectangle = new RectangleAnnotation()
{
    X1 = 1,
    Y1 = 40,
    X2 = 2,
    Y2 = 20,                
};

// Add the rectangle annotation to the chart's annotations collection
chart.Annotations.Add(rectangle);
this.Content = chart;

Rectangle annotation in MAUI Chart

Ellipse annotation

The EllipseAnnotation is used to draw an oval or a circle at specific points in the chart area. You can also specify the height and width of the EllipseAnnotation by using the Height and Width properties, respectively.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:EllipseAnnotation X1="2" X2="4" Y1="10" Y2="15" Width="20" Height="20"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();

// Create an instance of EllipseAnnotation to display an ellipse on the chart.
var ellipse = new EllipseAnnotation()
{
    X1 = 2,
    Y1 = 10,
    X2 = 4,
    Y2 = 15,    
    Width = 20,
    Height = 20
};

// Add the ellipse annotation to the chart's annotations collection.
chart.Annotations.Add(ellipse);
this.Content = chart;

Ellipse annotation in MAUI Chart

NOTE

When the X2 and Y2 properties of the EllipseAnnotation are set, the Height and Width properties become ineffective.

Line annotation

The LineAnnotation is used to draw a line at specific points in the chart area.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:LineAnnotation X1="0.5" Y1="10" X2="3.5" Y2="20" Text="Line"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();

// Create and configure a LineAnnotation with specified coordinates
var line = new LineAnnotation()
{
    X1 = 0.5,
    Y1 = 10,
    X2 = 3.5,
    Y2 = 20,
    Text = "Line"
};

// Add the line annotation to the annotations collection of the chart
chart.Annotations.Add(line);
this.Content = chart;

Line Annotation in MAUI Chart

Vertical and Horizontal line annotations

The VerticalLineAnnotation and HorizontalLineAnnotation are used to draw vertical and horizontal lines at specific points in the chart area.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:VerticalLineAnnotation X1="2"/>
        <chart:HorizontalLineAnnotation Y1="20"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
// Create a vertical line annotation
var verticalLineAnnotation = new VerticalLineAnnotation()
{
    X1 = 2,
};

// Create a horizontal line annotation
var horizontalLineAnnotation = new HorizontalLineAnnotation()
{
    Y1 = 20,
};

// Add the vertical and horizontal line annotations to the chart's annotations.
chart.Annotations.Add(verticalLineAnnotation);
chart.Annotations.Add(horizontalLineAnnotation);
this.Content = chart;

Vertical and horizontal Line Annotation in MAUI Chart

Displaying axis label for vertical and horizontal line annotations

The VerticalLineAnnotation and HorizontalLineAnnotation allow for the display of axis labels at the line’s position using the ShowAxisLabel property. The default value of the ShowAxisLabel property is false as shown in the code snippet below:

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:VerticalLineAnnotation X1="2.5" ShowAxisLabel="True"/>
        <chart:HorizontalLineAnnotation Y1="25" ShowAxisLabel="True"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
var verticalLineAnnotation = new VerticalLineAnnotation()
{
    X1 = 2.5,
    ShowAxisLabel = true // Display the label on the X-axis where the line intersects
};

var horizontalLineAnnotation = new HorizontalLineAnnotation()
{
    Y1 = 25,
    ShowAxisLabel = true // Display the label on the Y-axis where the line intersects
};

chart.Annotations.Add(verticalLineAnnotation);
chart.Annotations.Add(horizontalLineAnnotation);
this.Content = chart;

Vertical and horizontal Line Annotation with axis label in MAUI Chart

Axis label customization

The default appearance of the axis label can also be customized using the AxisLabelStyle property. The AxisLabelStyle property allows you to customize the axis labels by changing the font family, font size, font attributes, and text color. The following styles are used to customize the axis label:

  • TextColor - Gets or sets the text color of the label.
  • Background - Gets or sets the background color of the labels.
  • Margin - Gets or sets the margin of the label to customize the appearance of label.
  • FontFamily - Gets or sets the font family name for the label.
  • FontAttributes - Gets or sets the font style for the label.
  • FontSize - Gets or sets the font size for the label.

Adding arrow to vertical and horizontal line annotations

To display a single-headed arrow, set the LineCap property to Arrow. The default value of the LineCap property is None.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:VerticalLineAnnotation X1="2.5" LineCap="Arrow"/>
        <chart:HorizontalLineAnnotation Y1="25" LineCap="Arrow"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
. . .
var verticalLineAnnotation = new VerticalLineAnnotation()
{
    X1 = 2.5,
    LineCap = ChartLineCap.Arrow // Add an arrow cap to the end of the line
};

var horizontalLineAnnotation = new HorizontalLineAnnotation()
{
    Y1 = 25,
    LineCap = ChartLineCap.Arrow // Add an arrow cap to the end of the line
};

chart.Annotations.Add(verticalLineAnnotation);
chart.Annotations.Add(horizontalLineAnnotation);
this.Content = chart;

Vertical and horizontal Line Annotations with linecap in MAUI Chart

NOTE

The LineCap is applicable to line, horizontal, and vertical annotations.

Adding text in shape annotation

For all shape annotations, the text can be displayed using the Text property.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:EllipseAnnotation X1="2" X2="4" Y1="10" Y2="15" Text="Ellipse"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
...
var ellipseAnnotation = new EllipseAnnotation()
{
    X1 = 2,
    Y1 = 10,
    X2 = 4,
    Y2 = 15,
    Text = "Ellipse" // Set the text label for the ellipse.
};

chart.Annotations.Add(ellipseAnnotation);
this.Content = chart;

Annotation in MAUI Chart

Text customization in shape annotation

The Text in shape annotation also can be customized by using the LabelStyle property. The LabelStyle property provides options to customize the font-family, font-size, font-attributes and text color of axis labels.

  • TextColor - Gets or sets the text color of the label.
  • Background - Gets or sets the background color of the labels.
  • Margin - Gets or sets the margin of the label to customize the appearance of label.
  • FontFamily - Gets or sets the font family name for the label.
  • FontAttributes - Gets or sets the font style for the label.
  • FontSize - Gets or sets the font size for the label.
  • HorizontalTextAlignment - Gets or sets the horizontal alignment of the label.
  • VerticalTextAlignment - Gets or sets the vertical alignment of the label.

View annotation

The ViewAnnotation allows you to add annotations in the form of your own custom view using the View property at a specific area of interest in the chart area. Additionally, the ViewAnnotation can be aligned using the VerticalAlignment and HorizontalAlignment properties.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:ViewAnnotation X1="3" Y1="30">
            <chart:ViewAnnotation.View>
                <Image Source="cloud.png"/>
            </chart:ViewAnnotation.View>
        </chart:ViewAnnotation>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
...
// Define a new ViewAnnotation to add a graphical element to the chart.
var viewAnnotation = new ViewAnnotation()
{
    X1 = 3,
    Y1 = 30,
    View = new Image() { Source = "cloud.png" };
};

// Add the created ViewAnnotation to the chart's Annotations collection.
chart.Annotations.Add(viewAnnotation);
this.Content = chart;

View Annotation in MAUI Chart

Annotation Visibility

The IsVisible property of ChartAnnotation is used to toggle the visibility of the annotation.

<chart:SfCartesianChart>
    ...
    <chart:SfCartesianChart.Annotations>
        <chart:EllipseAnnotation X1="2" X2="4" Y1="10" Y2="15" Text="Ellipse" IsVisible="False"/>
    </chart:SfCartesianChart.Annotations>
</chart:SfCartesianChart>
SfCartesianChart chart = new SfCartesianChart();
...
var ellipseAnnotation = new EllipseAnnotation()
{
    X1 = 2,
    Y1 = 10,
    X2 = 4,
    Y2 = 15,
    Text = "Ellipse",
    IsVisible = false  // Set the visibility of the annotation
};

chart.Annotations.Add(ellipse);
this.Content = chart;