Experimental

Handling of native Excel charts in XLSX.jl is experimental and a work in progress. All aspects may be subject to change. Feedback is welcome!

Creating charts

julia> using XLSX, XLSX.Charts

addChart makes an empty chart of a given kind, and addSeries fills it. This page covers the c: schema; the newer kinds are in Creating chartEx charts.

A chart on a worksheet

julia> f = XLSX.newxlsx();

julia> ws = f[1];

julia> ws["A1"] = ["Region", "2024"];

julia> ws["A2:A5"] = ["North", "South", "East", "West"];

julia> ws["B2:B5"] = [10.0, 20.0, 15.0, 5.0];

julia> c = addChart(ws, :column; anchor = "D2:K17", title = "Revenue");

julia> addSeries(c, "B2:B5"; categories = "A2:A5", name_ref = "B1");

julia> XLSX.writexlsx("revenue.xlsx", f)
"C:\\Users\\...\\revenue.xlsx"

A column chart titled Revenue with one column for each of North, South, East and West

anchor is required, and is the cell range the chart covers — its top-left and bottom-right corners on the sheet. title is nothing for the title Excel generates itself, a string for typed text, or false for no title at all.

A chart is created empty because a c: chart part is valid with no series, so addChart and addSeries can be separate steps. That is not true of the cx: schema, where the data block is required.

The kinds

kind is one of these, each named after the Excel subtype it creates:

Clustered or plainStacked100% stacked
Column (vertical bars):column:stackedColumn:percentStackedColumn
Bar (horizontal):bar:stackedBar:percentStackedBar
Line:line:stackedLine:percentStackedLine
Line with markers:lineMarkers:stackedLineMarkers:percentStackedLineMarkers
Area:area:stackedArea:percentStackedArea

and :pie, :doughnut, :scatter, :bubble, :radar and :filledRadar, and :combo, a column and a line chart in one; see Combo charts.

Every chart kind addChart creates, each titled with its kind, from :column to :combo, as Excel draws them in a workbook made by XLSX.newxlsx

Each comes from a chart part Excel itself wrote, kept verbatim in the package, so a created chart is what Excel would have produced for that kind — including its style and color parts. Kinds with no template yet throw rather than approximate; see Limitations.

A chart on its own sheet

Pass the file rather than a worksheet to create a chartsheet:

julia> cs = addChart(f, :line; sheetname = "Trend", title = "Revenue over time");

sheetname defaults to Chart1, Chart2, … as Excel names them. A chartsheet holds one chart, positioned absolutely rather than anchored to cells, so there is no anchor to give.

Its series still take their data from a worksheet, and must name the sheet, since there is no sheet of its own for an unqualified range to mean:

julia> addSeries(cs, "Sheet1!B2:B5"; categories = "Sheet1!A2:A5");

Referring to data

A series' values, categories, name_ref and bubble_sizes all take the same forms:

  • A range string — "B2:B5", or "Sheet1!B2:B5" to name the sheet. An unqualified range means the chart's own sheet.
  • A defined name, which resolves through the workbook.
  • A reference object: XLSX.SheetCellRange, XLSX.CellRange and the rest of the range types.

For a table, XLSX.gettablerange gives the ranges, header cell included:

julia> ts = XLSX.addsheet!(f, "Sales");

julia> ts["A1"] = "Region"; ts["B1"] = "Item"; ts["C1"] = "Amount";

julia> ts["A2:A6"] = reshape(["North", "North", "South", "South", "East"], 5, 1);

julia> ts["B2:B6"] = reshape(["Widgets", "Gadgets", "Widgets", "Gadgets", "Widgets"], 5, 1);

julia> ts["C2:C6"] = reshape([120.0, 85.0, 200.0, 140.0, 95.0], 5, 1);

julia> t = XLSX.addtable!(ts, "A1:C6"; name = "Sales", style="TableStyleMedium2");

julia> tc = addChart(ts, :column; anchor = "E2:L18", title = "Sales by item");

julia> addSeries(tc, XLSX.gettablerange(t, "Amount");
                 categories = XLSX.gettablerange(t, "Item"),
                 name_ref = XLSX.gettablerange(t, "Amount"; header = true));

julia> only(getChartSeries(tc)).name
"Amount"

An Excel Table of sales by item beside a column chart of its Amount column

Whatever you pass, the chart part stores a sheet-qualified absolute reference, as Excel does. The cells' current values are cached in the chart at the same time, so the series reads back without opening the file in Excel — see the chart cache.

Cells holding formulas written by XLSX.setFormula have no values until Excel recalculates them, so a series plotting them is cached empty. Excel recalculates when it opens the file and draws the chart from the results, so it looks the same there; only reading the series back before then finds no values. A Likert chart plots formulas this way, so that sorting the data in Excel reorders the chart.

name and name_ref differ: name is the series name as literal text, while name_ref points at a cell holding it, which is what Excel writes when you select a header row. Pass one or neither, not both.

Series options

addSeries takes the common formatting inline, so a series can be styled as it is added rather than in a second pass:

julia> addSeries(c, "C2:C5"; categories = "A2:A5", name = "2025", color = "FF0000");
KeywordApplies toTakes
coloreverything but pie and doughnuta color name, hex, a Colorant, a SchemeColor, or a scheme name such as "accent4"
markersevery line kind, radar (not filled), scattera symbol such as :circle, or false for none
smoothevery line kind, scattertrue or false — whether the line is curved
linescattertrue to join the points

An option that doesn't apply to the chart's kind throws rather than being ignored, so a mistake is caught rather than silently dropped. Pie and doughnut charts color their points individually rather than by series, which is why color has no meaning there.

Without color, series take the theme's accent colors in turn, as Excel does. Anything not covered here is set afterwards with the functions in Formatting charts.

A few combinations are rejected because the result would draw nothing or is under-specified: a bubble series needs both categories (its X values) and bubble_sizes, and a scatter series with markers = false needs line = true.

Chart subtypes

Excel's Insert menu offers several subtypes of most chart kinds. Some of them are set series by series with the keywords above, and others are separate kinds.

Scatter

There is one :scatter kind. Each series chooses one of Excel's five scatter subtypes with markers, line and smooth:

Excel subtypeaddSeries keywords
Scatternone: markers only is the default
Scatter with Smooth Lines and Markersline = true, smooth = true
Scatter with Smooth Linesline = true, smooth = true, markers = false
Scatter with Straight Lines and Markersline = true
Scatter with Straight Linesline = true, markers = false
julia> c = addChart(ws, :scatter; anchor = "D2:K17", title = "Smooth lines");

julia> addSeries(c, "B2:B6"; categories = "A2:A6", name_ref = "B1",
                 line = true, smooth = true, markers = false);

On a scatter or bubble chart categories holds the X values, which Excel calls "Series X values" and writes as c:xVal. The keyword has the same name for every chart kind, and getChartData and getChartRanges read the X values back as categories too.

Line and radar

Line and radar charts take their subtypes from markers in the same way:

Excel subtypeHow to create it
Line:line
Line with Markers:lineMarkers, or markers = true (or a symbol) on a :line series
Stacked Line with Markers:stackedLineMarkers, or markers = true on a :stackedLine series
100% Stacked Line with Markers:percentStackedLineMarkers, or markers = true on a :percentStackedLine series
Radar:radar
Radar with Markers:radar with markers = true (or a symbol)

smooth = true curves a line series. Excel offers this in the series' format pane rather than as a subtype. Filled radar is a kind of its own, :filledRadar, and takes neither keyword: its series are filled areas.

Subtypes that are separate kinds

The stacked and 100% stacked subtypes of column, bar, line and area are kinds, in the table under The kinds, as are:

Excel subtypeKind
Pie, Doughnut:pie, :doughnut
Filled Radar:filledRadar
Bubble:bubble
Clustered Column – Line on Secondary Axis:combo

Subtypes that cannot be created

Excel's 3-D subtypes, and its stock, surface and of-pie charts, can't be created yet. They can still be read. See Limitations.

The subtype keywords apply to one series at a time, so one chart can mix subtypes, as it can in Excel.

Adding to a chart Excel made

addSeries reads the chart's kind back from the part rather than from anything the package recorded, so it works on a chart Excel created exactly as on one addChart made:

julia> g = XLSX.opentemplate("chart_basic.xlsx");

julia> ec = getCharts(g)[1]
XLSX.Charts.Chart "chart1" on sheet "Data" at G9:N23
  title: "Revenue by Region"
  type: barChart
  series: 2
    [1] 2024 - Data!$B$2:$B$5 (4 pts)
    [2] 2025 - Data!$C$2:$C$5 (4 pts)

julia> addSeries(ec, "Data!D2:D5"; categories = "Data!A2:A5", name = "2026");

julia> ec
XLSX.Charts.Chart "chart1" on sheet "Data" at G9:N23
  title: "Revenue by Region"
  type: barChart
  series: 3
    [1] 2024 - Data!$B$2:$B$5 (4 pts)
    [2] 2025 - Data!$C$2:$C$5 (4 pts)
    [3] 2026 - Data!$D$2:$D$5 (4 pts)

The new series takes the next accent color and the chart's own style, so it looks like the ones already there.

julia> [getSeriesFill(ec, i).value.fgcolor.val for i in 1:3]
3-element Vector{String}:
 "accent1"
 "accent2"
 "accent3"

A chart with more than one group — a combo chart — takes a group keyword to say which group a series joins; see Combo charts.

Combo charts

:combo is Excel's "Clustered Column – Line on Secondary Axis": a column group on the primary axes and a line group on secondary axes of its own, so the two can plot values of different sizes. Pass group to say which group each series joins:

julia> ws["A1"] = ["" "Units" "Margin"; "Q1" 120 0.31; "Q2" 135 0.28; "Q3" 150 0.35; "Q4" 160 0.33];

julia> cc = addChart(ws, :combo; anchor = "D2:K17", title = "Units and margin");

julia> addSeries(cc, "B2:B5"; categories = "A2:A5", name_ref = "B1", group = :column);

julia> addSeries(cc, "C2:C5"; categories = "A2:A5", name_ref = "C1", group = :line);

A combo chart titled Units and margin: units as columns against the left axis, and margin as a line against a second axis on the right

group is :column or :line. It is required on a combo chart and refused on any other, so a series can't land in a group by accident. Each series is formatted as Excel formats one in that group, and takes the options of a :column or :line series: markers = true on a line gives Excel's Line with Markers formatting, and smooth curves it. Series are numbered, and take the accent colors in turn, across the whole chart, as Excel numbers them.

The same works on a combo chart Excel made, provided it has one column group or one line group to add to; a chart with neither, or with two of the one asked for, throws. Changing which axes a group uses is not supported.

Making a chart a combo chart

makeCombo turns an existing :column, :stackedColumn or :line chart into the same combo, as Excel's Change Chart Type → Combo does. The last series becomes the line, on new secondary axes, and the others clustered columns:

julia> c = addChart(ws, :column; anchor = "D20:K35");

julia> addSeries(c, "B2:B5"; categories = "A2:A5", name_ref = "B1");

julia> addSeries(c, "C2:C5"; categories = "A2:A5", name_ref = "C1");

julia> makeCombo(c);

julia> [s.charttype for s in getChartSeries(c)]
2-element Vector{Symbol}:
 :barChart
 :lineChart

What Excel keeps, makeCombo keeps: the chart's title, legend and axes, axis titles included, and the formatting of each series that stays a column (or, from a line chart, the line). A series that changes type takes the formatting Excel gives a series of its new group, keeping its name, data and data labels. A stacked chart's columns become clustered, as in Excel. The chart needs two series or more; to start a combo from nothing, use addChart(ws, :combo; …).

Deleting a chart

deleteChart deletes a chart on a worksheet, whether XLSX.jl or Excel made it, with everything only it uses. The data it plotted is not changed:

julia> deleteChart(getChart(xf, "chart1"))

A chart on a chartsheet is the whole sheet: delete it with XLSX.deletesheet!.

Themes

A created chart's colors are theme references, not fixed values, so the chart follows the workbook's theme the way Excel's own charts do.

One consequence worth knowing: a workbook from XLSX.newxlsx() carries an older Office theme than current Excel, so charts created in a new workbook show that theme's colors rather than the ones Excel 365 would use. A chart added to a workbook Excel created uses that workbook's theme and matches.

See also