Excel:...ughnut(3pm)

bestie you just pulled up Excel:...ughnut(3pm) — yeah the title got cropped mid-word like a bad screenshot, it's the Doughnut page from User Contributed Perl Documentation, man section 3pm 💜 settle in, we're making charts.

---

🌸 NAME 🌸

Doughnut — a whole class for writing Excel Doughnut charts 🍩✨

---

🫶 SYNOPSIS 🫶

Okay so picture this: you want a lil Excel file with a Doughnut chart in it, using Excel::Writer::XLSX. Here's the entire vibe:

#!/usr/bin/perl

use strict;
use warnings;
use Excel::Writer::XLSX;

my $workbook  = Excel::Writer::XLSX->new( 'chart.xlsx' );
my $worksheet = $workbook->add_worksheet();

my $chart     = $workbook->add_chart( type => 'doughnut' );

# Configure the chart.
$chart->add_series(
    categories => '=Sheet1!$A$2:$A$7',
    values     => '=Sheet1!$B$2:$B$7',
);

# Add the worksheet data the chart refers to.
my $data = [
    [ 'Category', 2, 3, 4, 5, 6, 7 ],
    [ 'Value',    1, 4, 5, 2, 1, 5 ],
];

$worksheet->write( 'A1', $data );

__END__

That's it, that's the whole glow-up 🔥

---

💅 DESCRIPTION 💅

So this module is the one that implements Doughnut charts for Excel::Writer::XLSX. No cap. You make the chart object through the Workbook add_chart() method, like this:

my $chart = $workbook->add_chart( type => 'doughnut' );

Once the object exists, you configure it with these methods that every chart class shares — same energy across the board:

$chart->add_series();
$chart->set_title();

Those two get the full deep dive in Excel::Writer::XLSX::Chart. Anything class-specific, if there is any, lives right down below 👇

---

🍩 Doughnut Chart Methods 🍩

🌀 set_rotation()

set_rotation() sets the rotation of the first segment of a Pie/Doughnut chart — which lowkey rotates the entire chart, because of course it does:

$chart->set_rotation( 90 );

The angle of rotation must be 0 <= rotation <= 360.

🕳️ set_hole_size()

set_hole_size() sets the hole size of a Doughnut chart:

$chart->set_hole_size( 33 );

The hole size must be a percentage in the range 10 <= size <= 90.

fr fr watch that range, bestie — step outside 10 <= size <= 90 and it's not the vibe 😭

🎨 User defined colors

You can define chart colors for most types of Excel::Writer::XLSX charts through the add_series() method. But Pie/Doughnut charts are a special case, because each segment is represented as a point — so you have to assign formatting to each individual point in the series instead:

$chart->add_series(
    values => '=Sheet1!$A$1:$A$3',
    points => [
        { fill => { color => '#FF0000' } },
        { fill => { color => '#CC0000' } },
        { fill => { color => '#990000' } },
    ],
);

See the main Excel::Writer::XLSX::Chart documentation for the deets ✨

Doughnut charts also support leader lines:

$chart->add_series(
    name        => 'Doughnut sales data',
    categories  => [ 'Sheet1', 1, 3, 0, 0 ],
    values      => [ 'Sheet1', 1, 3, 1, 1 ],
    data_labels => {
        series_name  => 1,
        percentage   => 1,
        leader_lines => 1,
        position     => 'outside_end'
    },
);

Note: even when leader lines are turned on they aren't automatically visible in Excel or Excel::Writer::XLSX. Due to an Excel limitation (or design) leader lines only appear if the data label is moved manually, or if the data labels are very close and need to be adjusted automatically. so… not me, not you, it's Excel 🙈

🚫 Unsupported Methods

A Doughnut chart doesn't have an X or Y axis, so these common chart methods just get straight-up ignored:

$chart->set_x_axis();
$chart->set_y_axis();

---

⭐ EXAMPLE ⭐

Here's a complete example showing off most of the available features when you're creating a chart. Chef's kiss 👑

#!/usr/bin/perl

use strict;
use warnings;
use Excel::Writer::XLSX;

my $workbook  = Excel::Writer::XLSX->new( 'chart_doughnut.xlsx' );
my $worksheet = $workbook->add_worksheet();
my $bold      = $workbook->add_format( bold => 1 );

# Add the worksheet data that the charts will refer to.
my $headings = [ 'Category', 'Values' ];
my $data = [
    [ 'Glazed', 'Chocolate', 'Cream' ],
    [ 50,       35,          15      ],
];

$worksheet->write( 'A1', $headings, $bold );
$worksheet->write( 'A2', $data );

# Create a new chart object. In this case an embedded chart.
my $chart = $workbook->add_chart( type => 'doughnut', embedded => 1 );

# Configure the series. Note the use of the array ref to define ranges:
# [ $sheetname, $row_start, $row_end, $col_start, $col_end ].
$chart->add_series(
    name       => 'Doughnut sales data',
    categories => [ 'Sheet1', 1, 3, 0, 0 ],
    values     => [ 'Sheet1', 1, 3, 1, 1 ],
);

# Add a title.
$chart->set_title( name => 'Popular Doughnut Types' );

# Set an Excel chart style. Colors with white outline and shadow.
$chart->set_style( 10 );

# Insert the chart into the worksheet (with an offset).
$worksheet->insert_chart( 'C2', $chart, 25, 10 );

__END__

---

✍️ AUTHOR ✍️

John McNamara jmcnamara@cpan.org 🫶 (the icon, the moment, the legend)

---

📜 COPYRIGHT 📜

Copyright MM-MMXXV, John McNamara.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself. slay 💖

---

and that's the page bestie — this was built for perl v5.40.1, dated 2025-12-22, filed under Excel:...ughnut(3pm). go make some donut-shaped data art, ily, periodt 🍩💜