Introduction

This guide shows how to build native Word charts with Aspose.Words FOSS for .NET — the same drawing objects Word itself creates when you use Insert > Chart — entirely from code. A chart added this way is not a picture; it is a Chart object embedded in the document’s OOXML package, with a data series model, axes, a legend, and a data table that Word can still open and edit after the file is saved. This post is a deep dive into that Chart API: how to create a chart, add series data, and reach the axis, legend, data label, and formatting objects that control how it renders.

The library is MIT-licensed and has no native dependencies. It targets .NET Standard 2.0, so the code in this post runs unchanged on .NET Framework 4.6.2+ and .NET 6, 8, and 10. A NuGet package has not been published yet, so building from source is currently the way to get the library — see Quick Start below. Everything shown here is the same chart engine used by the commercial Aspose.Words for .NET; this edition includes the full chart object model but not page layout or rendering, so a chart’s on-page position is not computed and the document cannot be exported to PDF or an image.

What’s Included

Creating a Chart and Adding a Data Series

DocumentBuilder.InsertChart(chartType, width, height) inserts a chart shape at the current position and returns a Shape; its Chart property is the entry point for everything else. A newly inserted chart already has a default series, so most code clears it first and adds its own data through Chart.Series, a ChartSeriesCollection.

using Aspose.Words;
using Aspose.Words.Drawing.Charts;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

string[] categories = new string[] { "AW Category 1", "AW Category 2", "AW Category 3" };
chart.Series.Add("AW Series 1", categories, new double[] { 4.3, 2.5, 3.5 });

ChartSeriesCollection.Add has overloads for category/value pairs (as above), X/Y value pairs, dated series, and bubble series with an extra size value. On an individual ChartSeries, Add(xValue), Add(xValue, yValue), and Add(xValue, yValue, bubbleSize) append single points, Insert places a point at a given index, and Clear() / ClearValues() remove series data without necessarily removing the series object itself.

Chart Types and Series Types

ChartType — the enum passed to InsertChart — has around 40 members covering the standard Word chart families: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall, and Funnel, plus stacked, percent-stacked, and 3D variants of several of them (Bar3D, ColumnStacked, Area3DPercentStacked, and so on).

A related but distinct enum, ChartSeriesType, appears on ChartSeries.SeriesType and ChartSeriesGroup.SeriesType and describes the type of an individual series or series group rather than the chart as a whole. It carries the same members as ChartType plus two more — ParetoLine and RegionMap — that ChartType doesn’t expose directly. ChartSeriesGroup is what makes combo charts possible: Chart.SeriesGroups (a ChartSeriesGroupCollection) holds one group per series type in the chart, and each group has its own AxisX/AxisY pair and layout properties such as Overlap, GapWidth, BubbleScale, and DoughnutHoleSize.

Axes, Gridlines, and Scaling

Chart.AxisX, AxisY, and AxisZ (plus the Axes collection) return ChartAxis objects. Each axis has a Type (ChartAxisType.Category, Series, or Value), tick mark settings (MajorTickMark, MinorTickMark — Cross, Inside, Outside, or None), gridline flags (HasMajorGridlines, HasMinorGridlines), and unit control (MajorUnit, MinorUnit, and their *IsAuto counterparts). ChartAxis.Scaling returns an AxisScaling object whose Minimum and Maximum are AxisBound values — AxisBound.IsAuto reports whether the bound is computed automatically, and the parameterized constructors (AxisBound(value), AxisBound(datetime)) set an explicit numeric or date bound. A category axis can be pinned to text or time categories through ChartAxis.CategoryType (AxisCategoryType.Automatic, Category, or Time), and ChartAxis.Title exposes a ChartAxisTitle with its own Text, Show, and Font.

Legend, Data Table, and Chart Title

Chart.Legend returns a ChartLegend, whose Position (a LegendPosition of None, Bottom, Left, Right, Top, or TopRight) controls where it renders relative to the plot area; LegendEntries is a ChartLegendEntryCollection of individual ChartLegendEntry objects, each with its own Font and IsHidden flag for hiding a single series from the legend without removing it from the chart. Chart.DataTable (a ChartDataTable) renders the series values as a grid beneath the chart when Show is set, with HasLegendKeys, HasHorizontalBorder, HasVerticalBorder, and HasOutlineBorder controlling its appearance. Chart.Title is a ChartTitle with Text and Show properties, following the same pattern as the axis titles.

Data Labels, Data Points, and Markers

ChartSeries.HasDataLabels turns on data labels for a series, and ChartSeries.DataLabels (a ChartDataLabelCollection) or an individual ChartDataLabel from it controls what each label shows: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey, and ShowBubbleSize are independent flags, and Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit, and others) places the label relative to its point. ChartSeries.DataPoints gives per-point access through ChartDataPoint, which carries its own Marker (a ChartMarker with Symbol from the MarkerSymbol enum and a Size), Explosion (for pulling out a pie slice), and Format. Every chart element that can be filled or outlined — series, data points, the legend, the title, the data table — exposes a ChartFormat through its Format property, with Fill, Stroke, and ShapeType (ChartShapeType) properties and a SetDefaultFill() method to reset it. One caveat worth knowing: the theme-linked variants of fill and stroke color on ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor, and their tint/shade counterparts) are not implemented in this edition — set plain Fill/Stroke colors instead of theme-color references. Chart.Style (a ChartStyle such as Muted, Saturated, Gradient, Outline, or Black) applies a predefined look to the whole chart in one step.

Quick Start

Build the library from source — a NuGet package has not been published yet:

git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release

Then add a project reference to Aspose.Words.csproj from your application. With the reference in place, this creates a line chart with one series and saves it to DOCX:

using Aspose.Words;
using Aspose.Words.Drawing.Charts;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

string[] categories = new string[] { "AW Category 1", "AW Category 2", "AW Category 3" };
chart.Series.Add("AW Series 1", categories, new double[] { 4.3, 2.5, 3.5 });

doc.Save("chart.docx");
Console.WriteLine("Saved chart.docx");

Open chart.docx in Word and the chart is fully editable — right-click it and choose “Edit Data” to see the same three categories and values written above.

Supported Formats

FormatExtensionReadWrite
DOCX.docx✓✓
DOCM.docm✓✓
DOTX.dotx✓✓
DOTM.dotm✓✓
Flat OPC (all variants)(various)✓✓
Markdown.md✓✓
Text.txt✓✓

Charts built with the Chart API are OOXML drawing objects, so they round-trip across the DOCX-family formats above (DOCX, DOCM, DOTX, DOTM, and Flat OPC). This edition cannot export to PDF, XPS, or images and cannot print, so nothing renders a chart to a bitmap — the chart stays a live, editable object inside the Word file. The additional format converters removed from this edition (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, and WordML) are the same subsystems excluded everywhere else in the library, not something specific to charts.

Open Source & Licensing

Aspose.Words FOSS for .NET is released under the MIT license, free for commercial and personal use with no royalties or redistribution restrictions. The full source, including the chart classes referenced in this post, is available on GitHub in the Aspose.Words FOSS for .NET repository.

Getting Started