| title | page_title | description | slug | tags | published | position |
|---|---|---|---|---|---|---|
Label Template and Format |
Chart - Label Template and Format |
Use Label Template and Format their text in the Chart for Blazor. |
components/chart/label-template-format |
telerik,blazor,chart,label,template,format |
true |
22 |
The Chart for Blazor can render labels on the axes, series data points and legend. You can control those texts not only through the values you data bind, but also through format strings or templates.
To turn on series labels, you must set their Visible property to true under the corresponding ChartSeriesLabels tag. The series labels are turned off by default to avoid clutter and to make the charts easier to read.
You can jump to the following sections in this article:
Where the labels are numerical (series values, the value axis), you can format those strings through the Format property of the corresponding labels inner tag. This lets you set standard numeric format strings to the values to showcase, for example, percentage, currency, and so on.
caption Format numerical values through format strings
Standard number format strings
<TelerikChart>
<ChartSeriesItems>
<ChartSeries Type="ChartSeriesType.Line" Data="@chartData" Name="Revenue"
Field="@nameof(MyChartDataModel.TheValue)" CategoryField="@nameof(MyChartDataModel.TheCategory)">
<ChartSeriesLabels Visible="true" Format="{0:C2}"></ChartSeriesLabels>
</ChartSeries>
</ChartSeriesItems>
<ChartValueAxes>
<ChartValueAxis>
<ChartValueAxisLabels Format="{0:C0}"></ChartValueAxisLabels>
</ChartValueAxis>
</ChartValueAxes>
<ChartLegend Position="ChartLegendPosition.Right">
</ChartLegend>
</TelerikChart>
@code {
public class MyChartDataModel
{
public double TheValue { get; set; }
public string TheCategory { get; set; }
}
public List<MyChartDataModel> chartData = new List<MyChartDataModel>
{
new MyChartDataModel
{
TheValue = 20000,
TheCategory = "2017"
},
new MyChartDataModel
{
TheValue = 300000,
TheCategory = "2018"
},
new MyChartDataModel
{
TheValue = 400000,
TheCategory = "2019"
}
};
}To set a template for the corresponding label, use the Template property in the corresponding Label inner tag of the element you want to customize, for example, under ChartSeriesLabels or under ChartValueAxisLabels.
After the example, you can find lists with the available fields you can use in templates.
To add a new line, use the \n symbol. The other available objects are added through the #=theObject# syntax. You can find more details in the code samples below (including simple if-block logic).
The general syntax of the templates is based on the Kendo Templates. Note that the chart labels are not HTML elements and you cannot use HTML in them, only plain strings are allowed. Also, the various helper functions that come from the Kendo jQuery library are not available in Blazor (for example, kendo.toString() or kendo.format()).
To format the values, you need to call a JavaScript function that will return the desired new string based on the template value you pass to it. You can find examples of this in the [How to format the percent in a label for a pie or donut chart]({%slug chart-format-percent%}) knowledge base article and the Label Format - Complex Logic sample project.
caption Custom templates in labels
Label templates
<TelerikChart>
<ChartSeriesItems>
<ChartSeries Type="ChartSeriesType.Line" Data="@chartData" Name="Revenue" Color="red"
Field="@nameof(MyChartDataModel.TheValue)" CategoryField="@nameof(MyChartDataModel.TheCategory)">
<ChartSeriesLabels Visible="true" Template="@MySeriesTemplate"></ChartSeriesLabels>
</ChartSeries>
</ChartSeriesItems>
<ChartCategoryAxes>
<ChartCategoryAxis>
<ChartCategoryAxisLabels Template="@MyCategoryAxisTemplate"></ChartCategoryAxisLabels>
</ChartCategoryAxis>
</ChartCategoryAxes>
<ChartValueAxes>
<ChartValueAxis>
<ChartValueAxisLabels Template="@MyValueAxisTemplate"></ChartValueAxisLabels>
</ChartValueAxis>
</ChartValueAxes>
<ChartTitle Text="Revenue per product"></ChartTitle>
<ChartLegend Position="ChartLegendPosition.Right">
<ChartLegendLabels Template="@MyLegendItemTemplate"></ChartLegendLabels>
</ChartLegend>
</TelerikChart>
@code {
public string MySeriesTemplate = "value: #=value#\nfor category: #=category#\nextra info: #=dataItem.ExtraData#";
public string MyCategoryAxisTemplate = "#=value# quarter";
public string MyValueAxisTemplate = "#=value# million";
public string MyLegendItemTemplate = "#=series.color#: #=text#";
public class MyChartDataModel
{
public double TheValue { get; set; }
public string ExtraData { get; set; }
public string TheCategory { get; set; }
}
public List<MyChartDataModel> chartData = new List<MyChartDataModel>
{
new MyChartDataModel
{
ExtraData = "one",
TheValue = 2,
TheCategory = "first"
},
new MyChartDataModel
{
ExtraData = "two\nlines",
TheValue = 3,
TheCategory = "second"
},
new MyChartDataModel
{
ExtraData = "three",
TheValue = 4,
TheCategory = "third"
}
};
}In a series label template, you can use the following fields:
category- the category name. Available for area, bar, column, donut, line, pie series.dataItem- the original data item used to construct the point. Will benullif binding to array. Sample syntax:#=dataItem.MyModelFieldName#.percentage- the point value represented as a percentage value. Available only for donut, pie and 100% stacked charts.stackValue- the cumulative point value on the stack. Available only for stackable series.value- the point value. Can be a number or object containing each bound field.
In a category axis label template, you can use the following fields:
value- the category valueformat- the default format of the label
In a value axis label template, you can use the following fields:
value- the label value
In a legend item label template, you can use the following fields:
text- the text the legend itemseries- the data seriesvalue- the point value (only for donut and pie charts)percentage- the point value represented as a percentage value. Available only for donut, pie and 100% stacked charts
In some cases, you want the series to have labels, but certain data points must not have a label. For example, in [stacked series]({%slug components/chart/stack%}) where a certain value is 0.
To do that, you need to:
- add conditional logic in the template that renders the desired content when your condition is met, and returns nothing when it is not.
- ensure the labels background is transparent so there are no leftover spots on the chart.
This example also showcases basic logic use in the templates that does not require external functions.
caption Hide labels with zero values
Conditional label display
<TelerikChart>
<ChartSeriesItems>
<ChartSeries Type="ChartSeriesType.Column" Data="@chartData" Name="Product 1 Sales"
Field="@nameof(MyChartDataModel.Value1)" CategoryField="@nameof(MyChartDataModel.TheCategory)">
<ChartSeriesLabels Visible="true" Template="@MySeriesTemplate" Background="transparent"></ChartSeriesLabels>
<ChartSeriesStack Enabled="true"></ChartSeriesStack>
</ChartSeries>
<ChartSeries Type="ChartSeriesType.Column" Data="@chartData" Name="Product 2 Sales"
Field="@nameof(MyChartDataModel.Value2)" CategoryField="@nameof(MyChartDataModel.TheCategory)">
<ChartSeriesLabels Visible="true" Template="@MySeriesTemplate" Background="transparent"></ChartSeriesLabels>
</ChartSeries>
</ChartSeriesItems>
</TelerikChart>
@code {
public string MySeriesTemplate = "# if (value != 0) { # #=value# #}#";
public class MyChartDataModel
{
public double Value1 { get; set; }
public double Value2 { get; set; }
public string TheCategory { get; set; }
}
public List<MyChartDataModel> chartData = new List<MyChartDataModel>
{
new MyChartDataModel
{
Value1 = 3,
Value2 = 2,
TheCategory = "Q1"
},
new MyChartDataModel
{
Value1 = 1,
Value2 = 0,
TheCategory = "Q2"
},
new MyChartDataModel
{
Value1 = 0,
Value2 = 0,
TheCategory = "Q3"
}
};
}