Cartesian chart control

The CartesianChart control is a 'ready to go' control to create plots using the Cartesian coordinate system, To get started all you need to do is assign the Series property with a collection of ICartesianSeries.

using LiveChartsCore;
using LiveChartsCore.SkiaSharpView;

namespace ViewModelsSamples.Bars.Basic
{
    public class ViewModel
    {
        public ISeries[] Series { get; set; }
            = new ISeries[]
            {
                new LineSeries<int>
                {
                    Values = new int[] { 4, 6, 5, 3, -3, -1, 2 }
                },
                new ColumnSeries<double>
                {
                    Values = new double[] { 2, 5, 4, -2, 4, -3, 5 }
                }
            };
    }
}

<lvc:CartesianChart
    Series="{Binding Series}">
</lvc:CartesianChart>

The main components of this control are:

• Series
• Axes
• Tooltip
• Legend

But notice in the previous code snippet we did not specify the Axes, Tooltip, Legend or the series colors, this is because LiveCharts will decide them based on the current theme of the library, you can also customize any of these properties when you require it, this article will cover the most common scenarios.

Series

There are multiple series available in the library, you can add one or mix them all in the same chart, every series has unique properties, any image bellow is a link to an article explaining more about them.

Line series

Column series

Scatter series

Step line series

Heat series

Candle sticks series

Stacked line series

Stacked column series

Stacked step line series

Box series

Error series

Bubble series

Axes

A CartesianChart has 2 axes, the YAxis and the XAxis properties, an IAxis besides de visual customization such as labels format and separators paints it also controls multiple important features such as the Zooming, the Panning, the Scale (log) and the Paging.

This is a brief sample about how to use the main features of the Axis class, you can find a more detailed article at the button below or at the API explorer.

Go to the full axes article

Axes.SeparatorsStyle

using LiveChartsCore;
using LiveChartsCore.SkiaSharpView;
using LiveChartsCore.SkiaSharpView.Painting;
using LiveChartsCore.SkiaSharpView.Painting.Effects;
using SkiaSharp;

namespace ViewModelsSamples.Bars.Basic
{
    public class ViewModel
    {
        public ISeries[] Series { get; set; }
            = new ISeries[] { new ColumnSeries<int> { Values = new[] { 2, 5, 4, -2, 4, -3, 5 } } };

        public Axis[] XAxes { get; set; }
            = new Axis[]
            {
                new Axis
                {
                    Name = "X Axis",
                    NamePaint = new SolidColorPaint(SKColors.Black), // mark

                    LabelsPaint = new SolidColorPaint(SKColors.Blue), // mark
                    TextSize = 10,

                    SeparatorsPaint = new SolidColorPaint(SKColors.LightSlateGray) { StrokeThickness = 2 }  // mark
                }
            };

        public Axis[] YAxes { get; set; }
            = new Axis[]
            {
                new Axis
                {
                    Name = "Y Axis",
                    NamePaint = new SolidColorPaint(SKColors.Red), // mark

                    LabelsPaint = new SolidColorPaint(SKColors.Green), // mark
                    TextSize = 20,

                    SeparatorsPaint = new SolidColorPaint(SKColors.LightSlateGray) // mark
                    { // mark
                        StrokeThickness = 2, // mark
                        PathEffect = new DashEffect(new float[] { 3, 3 }) // mark
                    } // mark
                }
            };
    }
}

<lvc:CartesianChart
    Series="{Binding Series}"
    XAxes="{Binding XAxes}"
    YAxes="{Binding YAxes}">
</lvc:CartesianChart>

Axes.Labels and Axes.Labelers

Series = new ObservableCollection<ISeries>
{
    new ColumnSeries<int>
    {
        Values = new ObservableCollection<int> { 200, 558, 458, 249 },
    }
};

XAxes = new List<Axis>
{
    new Axis
    {
        // Use the labels property to define named labels.
        Labels = new string[] { "Anne", "Johnny", "Zac", "Rosa" } // mark
    }
};

YAxes = new List<Axis>
{
    new Axis
    {
        // Now the Y axis we will display labels as currency
        // LiveCharts provides some common formatters
        // in this case we are using the currency formatter.
        Labeler = Labelers.Currency // mark

        // you could also build your own currency formatter
        // for example:
        // Labeler = (value) => value.ToString("C")

        // But the one that LiveCharts provides creates shorter labels when
        // the amount is in millions or trillions
    }
};

Zooming and panning

It is disabled by default, to enable it you must set the ZoomMode property.

<lvc:CartesianChart
    Series="{Binding Series}"
    TooltipPosition="Hidden"
    ZoomMode="X"> <!-- mark -->
</lvc:CartesianChart>

ZoomingSpeed property

Defines the zooming speed, it is of type double and goes from 0 to 1, where 0 is the slowest and 1 the fastest, do not confuse with animations seed, this property controls the new axis length (MaxLimit - MinLimit) when the Zoom() method is called.

<lvc:CartesianChart
    Series="{Binding Series}"
    ZoomingSpeed="0"> <!-- mark -->
</lvc:CartesianChart>

Clearing the current zooming or panning

Setting MinLimit and MaxLimit properties to null will clear the current zooming or panning, and will let the chart fit the view of the chart to the available data in the chart, the default value of both properties is null.

AnimationsSpeed property

Defines the animations speed of all the chart elements (axes, series, sections).

<lvc:CartesianChart
    Series="{Binding Series}"
    AnimationsSpeed="00:00:00.500"> <!-- 500 milliseconds --> <!-- mark -->
</lvc:CartesianChart>

EasingFunction property

This property defines the way the shapes in the chart animate, in other words it controls the way the IMotionProperties of all the chart elements (axes, series, sections) in the chart move from a state 'A' to state 'B'.

The property is of type Func<float, float>, it means that it is a function that takes a float argument (the time elapsed from 0 to 1), and returns float value as the result (the progress of the animation from 0 to 1), you can learn more about easing curves at this article.

<Container
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:lvcore="clr-namespace:LiveChartsCore;assembly=LiveChartsCore"> <!-- import the core ns --> <!-- mark -->

    <lvc:CartesianChart
        Series="{Binding Series}"
        AnimationsSpeed="00:00:00.500"
        EasingFunction="{Binding Source={x:Static lvcore:EasingFunctions.BounceOut}}"> <!-- mark -->
    </lvc:CartesianChart>
    
</Container>

Now the chart will animate following the BounceOut curve.

Now try the LiveChartsCore.EasingFunctions.Lineal function, it will animate things lineally as the time elapses.

Finally you can also build your own function:

public Func<float, float> Easing { get; set; } = time => time * time; // mark

<Control
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <lvc:CartesianChart
        Series="{Binding Series}"
        AnimationsSpeed="00:00:00.500"
        EasingFunction="{Binding Easing}"> <!-- mark -->
    </lvc:CartesianChart>

The library also provides some builders based on d3-ease easing curves, the builders.

Func easingCurve = LiveChartsCore.EasingFunctions.BuildCustomBackOut(0.8f);
Func easingCurve = LiveChartsCore.EasingFunctions.BuildCustomElasticOut(0.8f, 1.1f);
// there are more builders, check them out all, they start with Build{ function }({ args })

Disable animations

Settings the EasingFunction to null disables animations.

<lvc:CartesianChart
    EasingFunction="{x:Null}"> <!-- mark -->
</lvc:CartesianChart>

DrawMargin property

Defines the distance from the axes (or edge of the chart if there is no axis) to the draw margin area.

// Notice the constructor of the Margin class has multiple overloads
// https://livecharts.dev/api/2.0.0-rc2/LiveChartsCore.Measure.Margin
public LiveChartsCore.Measure.Margin Margin { get; set; } = new LiveChartsCore.Measure.Margin(100); // mark

<lvc:CartesianChart
    Series="{Binding Series}"
    DrawMargin="{Binding Margin}"> <!-- mark -->
</lvc:CartesianChart>

Tooltips

Tooltips are popups that help the user to read a chart as the pointer moves.

This is a brief sample about how to use the main features of the IChartTooltip<T> interface, you can find a more detailed article at the button below or at the API explorer.

Go to the full tooltips article

You can place a tooltip at Top, Bottom, Left, Right, Center or Hidden positions, for now tooltips for the PieChart class only support the Center position, default value is Top.

<lvc:CartesianChart
    Series="{Binding Series}"
    TooltipPosition="Top"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    TooltipPosition="Bottom"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    TooltipPosition="Left"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    TooltipPosition="Right"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    TooltipPosition="Center"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    TooltipPosition="Hidden"><!-- mark -->
</lvc:CartesianChart>

Legends

A legend is a visual element that displays a list with the name, stroke and fills of the series in a chart:

This is a brief sample about how to use the main features of the IChartLegend<T> interface, you can find a more detailed article at the button below or at the API explorer.

Go to the full legends article

You can place a legend at Top, Bottom, Left, Right or Hidden positions, notice the Hidden position will disable legends in a chart, default value is Hidden.

<lvc:CartesianChart
    Series="{Binding Series}"
    LegendPosition="Top"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    LegendPosition="Bottom"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    LegendPosition="Left"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    LegendPosition="Right"><!-- mark -->
</lvc:CartesianChart>
<lvc:CartesianChart
    Series="{Binding Series}"
    LegendPosition="Hidden"><!-- mark -->
</lvc:CartesianChart>

DrawMarginFrame property

This property defines a visual border for the DrawMargin.

using LiveChartsCore;
using LiveChartsCore.SkiaSharpView;
using LiveChartsCore.SkiaSharpView.Painting;
using SkiaSharp;

namespace ViewModelsSamples.Lines.Area
{
    public class ViewModel
    {
        public DrawMarginFrame DrawMarginFrame => new DrawMarginFrame
        {
            Fill = new SolidColorPaint(SKColors.AliceBlue),
            Stroke = new SolidColorPaint(SKColors.Black, 3)
        };

        public ISeries[] Series { get; set; } = new[] { ... };
    }
}

<lvc:CartesianChart
    Series="{Binding Series}"
    DrawMarginFrame="{Binding DrawMarginFrame}"><!-- mark -->
</lvc:CartesianChart>

Sections

A section is a visual area in a chart that highlights a range of values in an axis, to stablish the limits of a section you must use the Xi and Xj properties in the X axis, the Xi represents the start of the section while the Xj the end, the same goes for the Yi and Yj properties for the Y axis.

Xi: Gets or sets the xi, the value where the section starts at the X axis, set the property to null to indicate that the section must start at the beginning of the X axis, default is null.

Xj: Gets or sets the xj, the value where the section ends and the X axis, set the property to null to indicate that the section must go to the end of the X axis, default is null.

Yi: Gets or sets the yi, the value where the section starts and the Y axis, set the property to null to indicate that the section must start at the beginning of the Y axis, default is null.

Yj: Gets or sets the yj, the value where the section ends and the Y axis, set the property to null to indicate that the section must go to the end of the Y axis, default is null.

using LiveChartsCore;
using LiveChartsCore.SkiaSharpView;
using LiveChartsCore.SkiaSharpView.Painting;
using SkiaSharp;

namespace ViewModelsSamples.General.Sections
{
    public class ViewModel
    {
        public RectangularSection[] Sections { get; set; }
            = new RectangularSection[]
            {
                new RectangularSection
                {
                    // creates a section from 3 to 4 in the X axis
                    Xi = 3,
                    Xj = 4,
                    Fill = new SolidColorPaint(new SKColor(255, 205, 210))
                },

                new RectangularSection
                {
                    // creates a section from 5 to 6 in the X axis
                    // and from 2 to 8 in the Y axis
                    Xi = 5,
                    Xj = 6,
                    Yi = 2,
                    Yj = 8,
                    Fill = new SolidColorPaint(new SKColor(187, 222, 251))
                },

                 new RectangularSection
                {
                    // creates a section from 8 to the end in the X axis
                    Xi = 8,
                    Fill = new SolidColorPaint(new SKColor(249, 251, 231))
                }
            };

        public ISeries[] Series { get; set; } = new ISeries[] { ... };
    }
}

<lvc:CartesianChart
    Series="{Binding Series}"
    Sections="{Binding Sections}"><!-- mark -->
</lvc:CartesianChart>