Chart Nested Component Structure

• Aug 19, 2024
• 6 minutes to read

The DxChart component can include multiple sub-elements, such as a series, title, legend, or annotation. To display sub-elements on the chart plane, add the corresponding nested components to chart markup. You should declare nested components at appropriate nesting levels to render the chart component correctly.

This topic contains detailed information about available nesting levels and components permitted at each level.

Show the Full Structure

• DxChart<T>
  • Individual Series
    • DxChartSeriesPoint
      • DxChartSeriesPointImage
    • DxChartSeriesLabel
      • DxChartSeriesLabelConnector
      • DxChartFont
      • DxChartSeriesLabelBorder
    • DxChartSeriesValueErrorBar
    • DxChartAggregationSettings
    • DxChartSeriesLegendItem
      • DxChartSeriesLegendItem.TextTemplate
    • DxChartFinancialReduction (for financial series)
  • DxChartCommonSeries
    • SeriesTemplate
      • Individual Series
        • DxChartSeriesPoint
          • DxChartSeriesPointImage
        • DxChartSeriesLabel
          • DxChartSeriesLabelConnector
          • DxChartFont
          • DxChartSeriesLabelBorder
        • DxChartSeriesValueErrorBar
        • DxChartAggregationSettings
        • DxChartSeriesLegendItem
          • DxChartSeriesLegendItem.TextTemplate
        • DxChartFinancialReduction (for financial series)
  • DxChartTitle
    • DxChartSubTitle
  • DxChartLegend
    • DxChartTitle
      • DxChartSubTitle
  • DxChartArgumentAxis / DxChartValueAxis
    • DxChartAxisGridLines
    • DxChartAxisTick
    • DxChartAxisMinorTick
    • DxChartAxisTitle
      • DxChartFont
    • DxChartConstantLine
      • DxChartConstantLineLabel
      • DxChartFont
    • DxChartAxisRange
    • DxChartAxisLabel
      • DxChartFont
    • DxChartScaleBreak
    • DxChartAxisStrip
      • DxChartAxisStripLabel
        • DxChartFont
  • DxChartAnnotation
    • DxChartAnnotationImage
    • DxChartAnnotationBorder
    • DxChartAnnotationShadow
    • DxChartFont
  • DxChartTooltip
    • DxChartTooltip.ChildContent
  • DxChartPane
    • DxChartPaneBorder
  • DxChartZoomAndPanSettings
    • DxChartZoomAndPanDragBoxStyle
  • DxChartAnimationSettings
  • DxChartScrollBarSettings

First-Level Components

The Chart’s root level (<DxChart>...</DxChart>) can contain the following components:

• One or more individual series
• DxChartCommonSeries
• DxChartLegend
• DxChartTitle
• DxChartArgumentAxis
• One or more DxChartValueAxis
• One or more DxChartPane
• One or more DxChartAnnotation
• DxChartTooltip
• DxChartZoomAndPanSettings
• DxChartAnimationSettings
• DxChartScrollBarSettings

The following code snippet adds first-level components to chart markup. For a sample data source, refer to our GitHub repository.

Razor

<DxChart Data="@Sales.dataSource">
    <DxChartLegend AllowToggleSeries="true"
                   HorizontalAlignment="HorizontalAlignment.Center" />
    <DxChartTitle Text="Sales amount" />
    <DxChartArgumentAxis EndOnTick="false" />
    <DxChartValueAxis EndOnTick="false" />
    <DxChartPane Name="Pane1" />
    <DxChartPane Name="Pane2" />
    <DxChartLineSeries Name="2017" Filter="@((SaleInfo s) => s.Date.Year == 2017)"
                       ArgumentField="@(s => s.City)" ValueField="@(s => s.Amount)" 
                       Pane="Pane1" />
    <DxChartLineSeries Name="2018" Filter="@((SaleInfo s) => s.Date.Year == 2018)"
                       ArgumentField="@(s => s.City)" ValueField="@(s => s.Amount)"
                       Pane="Pane2" />
    <DxChartTooltip Enabled="true" Position="RelativePosition.Outside">
        <div style="margin: 0.75rem">
            <div>City: @context.Point.Argument</div>
            <div>Number of Sales: @context.Point.Value</div>
        </div>
    </DxChartTooltip>
    <DxChartZoomAndPanSettings ArgumentAxisZoomAndPanMode="ChartAxisZoomAndPanMode.Zoom" />
    <DxChartAnimationSettings Enabled="false" />
    <DxChartScrollBarSettings ArgumentAxisScrollBarVisible="true" />
</DxChart>

SaleInfo

using System;

public class SaleInfo {
    public int OrderId { get; set; }
    public string Region { get; set; }
    public string Country { get; set; }
    public string City { get; set; }
    public int Amount { get; set; }
    public DateTime Date { get; set; }
}

Sales

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

public class Sales {
    static IList<SaleInfo> dataSource;
    static Sales() {
        CreateDataSource();
    }

    public static Task<IQueryable<SaleInfo>> GetSalesAsync() {
        return Task.FromResult(dataSource.AsQueryable());
    }

    static void CreateDataSource() {
        dataSource = new List<SaleInfo> {
        new SaleInfo {
                OrderId = 10248,
                Region = "North America",
                Country = "United States",
                City = "New York",
                Amount = 1740,
                Date = DateTime.Parse("2017/01/06")
            },
            new SaleInfo {
                OrderId = 10249,
                Region = "North America",
                Country = "United States",
                City = "Los Angeles",
                Amount = 850,
                Date = DateTime.Parse("2017/01/13")
            },
            new SaleInfo {
                OrderId = 10250,
                Region = "North America",
                Country = "United States",
                City = "Denver",
                Amount = 2235,
                Date = DateTime.Parse("2017/01/07")
            },
            new SaleInfo {
                OrderId = 10251,
                Region = "North America",
                Country = "Canada",
                City = "Vancouver",
                Amount = 1965,
                Date = DateTime.Parse("2017/01/03")
            },
            new SaleInfo {
                OrderId = 10252,
                Region = "North America",
                Country = "Canada",
                City = "Edmonton",
                Amount = 880,
                Date = DateTime.Parse("2017/01/10")
            },
            new SaleInfo {
                OrderId = 10253,
                Region = "South America",
                Country = "Brazil",
                City = "Rio de Janeiro",
                Amount = 5260,
                Date = DateTime.Parse("2017/01/17")
            },
            new SaleInfo {
                OrderId = 10254,
                Region = "South America",
                Country = "Argentina",
                City = "Buenos Aires",
                Amount = 2790,
                Date = DateTime.Parse("2017/01/21")
            },
            new SaleInfo {
                OrderId = 10255,
                Region = "South America",
                Country = "Paraguay",
                City = "Asuncion",
                Amount = 3140,
                Date = DateTime.Parse("2017/01/01")
            },
            new SaleInfo {
                OrderId = 10256,
                Region = "Europe",
                Country = "United Kingdom",
                City = "London",
                Amount = 6175,
                Date = DateTime.Parse("2017/01/24")
            },
            new SaleInfo {
                OrderId = 10257,
                Region = "Europe",
                Country = "Germany",
                City = "Berlin",
                Amount = 4575,
                Date = DateTime.Parse("2017/01/11")
            },
            // ...
    };
    }
}

Second-Level Components

This section lists first-level components that can contain child components.

Individual Series

An individual series of any type can include:

• DxChartSeriesPoint
• DxChartSeriesLabel
• DxChartSeriesLegendItem
• DxChartAggregationSettings
• DxChartSeriesValueErrorBar

Financial series (DxChartCandlestickSeries and DxChartStockSeries) can also include DxChartFinancialReduction objects.

The following code snippet creates a line series and adds second-level components to series markup:

<DxChartLineSeries Name="2017" Filter="@((SaleInfo s) => s.Date.Year == 2017)"
                       ArgumentField="@(s => s.City)" ValueField="@(s => s.Amount)" 
                       Pane="Pane1">
    <DxChartSeriesPoint Color="@System.Drawing.Color.Orange" />
    <DxChartSeriesLabel Position="RelativePosition.Outside" />
    <DxChartSeriesLegendItem IconCssClass="oi oi-flag" />
    <DxChartAggregationSettings Enabled="true"
                                Method="ChartAggregationMethod.Sum" />
</DxChartLineSeries>

Common Series

The DxChartCommonSeries component can only contain the SeriesTemplate. The template should include at least one series. To specify series-related settings, add the corresponding components to series markup. For more information on supported child components, refer to the section above.

The following code snippet defines SeriesTemplate inside the DxChartCommonSeries component:

<DxChartCommonSeries NameField="@((SaleInfo s) => s.Date.Year)"
                     ArgumentField="@((SaleInfo s) => s.City)"
                     ValueField="@((SaleInfo s) => s.Amount)">
    <SeriesTemplate Context="settings">
        <DxChartLineSeries Settings="@settings">
            <DxChartSeriesPoint Color="@System.Drawing.Color.Orange" />
            <DxChartSeriesLabel Position="RelativePosition.Outside" />
            <DxChartSeriesLegendItem IconCssClass="oi oi-flag" />
            <DxChartAggregationSettings Enabled="true" Method="ChartAggregationMethod.Sum" />
          </DxChartLineSeries>
    </SeriesTemplate>
</DxChartCommonSeries>

Axes

The argument and value axes can contain the following components:

• DxChartAxisGridLines
• DxChartAxisTick
• DxChartAxisMinorTick
• DxChartAxisTitle
• DxChartConstantLine
• DxChartAxisRange
• DxChartAxisLabel
• DxChartScaleBreak
• One or more DxChartAxisStrip

The following code snippet adds second-level components to the markup of chart axes:

<DxChartArgumentAxis EndOnTick="false">
    <DxChartAxisGridLines Visible="true" />
</DxChartArgumentAxis>
<DxChartValueAxis EndOnTick="false">
    <DxChartConstantLine Value="60000" />
    <DxChartValueBreaks StartValue="10000" EndValue="15000" />
    <DxChartAxisRange StartValue="0" EndValue="82000" />
    <DxChartAxisLabel Format="ChartElementFormat.Thousands()" />
    <DxChartAxisTitle Text="Items" />
</DxChartValueAxis>

Title

The DxChartTitle component can contain the DxChartSubTitle.

<DxChartTitle Text="Sales amount">
    <DxChartSubTitle Text="by cities" />
</DxChartTitle>

Third-Level Components

This section lists second-level components that can contain child components.

Legend

The DxChartLegend component can contain DxChartTitle and DxChartSubTitle (inside the title’s markup) objects.

<DxChartLegend AllowToggleSeries="true"
               HorizontalAlignment="HorizontalAlignment.Center">
    <DxChartTitle Text="Sales amount">
        <DxChartSubTitle Text="by cities" />
    </DxChartTitle>
</DxChartLegend>

Legend Item

The DxChartSeriesLegendItem component can contain the TextTemplate that customizes a legend item’s text.

<DxChartLineSeries Name="2017" Filter="@((SaleInfo s) => s.Date.Year == 2017)"
                   ArgumentField="@(s => s.City)" ValueField="@(s => s.Amount)" 
                   Pane="Pane1">
    <DxChartSeriesLegendItem IconCssClass="oi oi-flag">
        <TextTemplate><b>Current year</b></TextTemplate>
    </DxChartSeriesLegendItem>
</DxChartLineSeries>

Constant Line

The DxChartConstantLine component can contain the DxChartConstantLineLabel that configures the constant line’s label.

<DxChartValueAxis EndOnTick="false">
    <DxChartConstantLine Value="60000">
        <DxChartConstantLineLabel Text="Planned Value" />
    </DxChartConstantLine>
</DxChartValueAxis>

Series Point

The DxChartSeriesPoint component can contain a DxChartSeriesPointImage object that customizes the series point image.

<DxChartLineSeries Name="2017" Filter="@((SaleInfo s) => s.Date.Year == 2017)"
                   ArgumentField="@(s => s.City)" ValueField="@(s => s.Amount)" 
                   Pane="Pane1">
    <DxChartSeriesPoint Color="@System.Drawing.Color.Orange">
        <DxChartSeriesPointImage Width="50" Height="50" />
    </DxChartSeriesPoint>
</DxChartLineSeries>

Series Label

The DxChartSeriesLabel component can contain the following child components:

DxChartSeriesLabelConnector

Customizes a line displayed between a point and its label.

DxChartFont

Contains the element’s font settings.

DxChartSeriesLabelBorder

Defines series label border settings.

<DxChartLineSeries Name="2017" Filter="@((SaleInfo s) => s.Date.Year == 2017)"
                   ArgumentField="@(s => s.City)" ValueField="@(s => s.Amount)" 
                   Pane="Pane1">
    <DxChartSeriesLabel Position="RelativePosition.Outside">
        <DxChartSeriesLabelConnector Width="3" />
        <DxChartFont Size="14" Weight="600" />
    </DxChartSeriesLabel>
</DxChartLineSeries>

Annotation

The DxChartAnnotation component can contain the following child components:

DxChartAnnotationImage

Defines settings for image annotations.

DxChartAnnotationBorder

Defines annotation border settings.

DxChartAnnotationShadow

Defines annotation shadow settings.

DxChartFont

Contains the element’s font settings.

<DxChartAnnotation Argument="new DateTime(2019, 9, 10)"
                   Series="AAPL"
                   Text="Watch Series 5"
                   Opacity="0.3">
    <DxChartAnnotationBorder Color="#FFC107" Width="2" CornerRadius="4" Opacity="0.8"/>
    <DxChartAnnotationShadow Color="#FFC107" Blur="6" Opacity="0.7"/>
</DxChartAnnotation>

Axis Strip

The DxChartAxisStrip component can contain a DxChartAxisStripLabel component that configures strip label settings.

<DxChartAxisStrip StartValue="@HighAverage"
                  Color="rgba(255, 155, 85, 0.15)">
    <DxChartAxisStripLabel Text="Above average high">
        <DxChartFont Color="@HighAverageColor" Weight="500" Size="14"/>
</DxChartAxisStripLabel>