PieChart Properties

Pie chart appearance and behavior

Since R2023b

PieChart properties control the appearance and behavior pie charts. By changing property values, you can modify certain aspects of these charts. Use dot notation to query and set properties.

p = piechart([1 2 3 4]);
p.Names = ["Apple","Peach","Pizza","Pumpkin"];

Labels

Title — Chart title

string vector | character vector | cell array of character vectors | categorical array

Chart title, specified as a string vector, character vector, cell array of character vectors, or categorical array. To create a multiline title, specify a string vector or cell array of character vectors. Each element in the array is a separate line of text.

Alternatively, you can call the title function to add a title to the chart.

piechart([1 2 3 4])
title("My Pie Chart")

Labels — Slice labels

string vector | cell array of character vectors

Slice labels, specified as a string vector or cell array of character vectors that has one value per slice.

Set this property if you want to change the labels that appear by default. The default labels might include the slice names depending on how you create your chart:

• If you create the chart with numeric or duration data without specifying the slice names, MATLAB^® assigns a default set of names to the Names property. However, the labels do not include those names. If you set the Names property explicitly, then the slice labels include the names.

• If you create the chart with categorical data, then the Names property contains the category names, and the slice labels include those names.

• If you create the chart with a table and specify a variable containing the names, then the Names property contains the names from that variable, and the slice labels include those names.

LabelsMode — How slices are labeled

"auto" | "manual"

How the slices are labeled, specified as "auto" or "manual".

• "auto" — Create and update the slice labels based on the Proportions and Names properties. If either of those properties change, the labels automatically update.

• "manual" — Do not update the labels. When you set the Labels property, the LabelsMode property automatically changes to "manual".

LabelStyle — Label style

"namepercent" (default) | "namedata" | "name" | "data" | "percent" | "none"

Since R2024a

Label style, specified as one of the values in the table. When changing between different label styles, you might need to resize the figure to maintain the same size pie chart. Setting this property has no effect if the LabelsMode property is set to "manual".

Value	Description	Example
"namepercent"	Display the Names and Proportions values (as percentages) next to the corresponding slices.
"namedata"	Display the Names and Data values next to the corresponding slices.
"name"	Display the Names values next to the corresponding slices.
"data"	Display the Data values next to the corresponding slices.
"percent"	Display the Proportions values (as percentages) next to the corresponding slices.
"none"	Do not display any labels.

LabelStyleMode — How label style is selected

"auto" (default) | "manual"

Since R2024a

How the label style is selected, specified as "auto" or "manual".

• "auto" — MATLAB selects the label style based on your data (numeric or categorical) and the value of the NamesMode property.

• "manual" — You specify the label style by setting the LabelStyle property.

LegendVisible — Legend visibility

"off" (default) | on/off logical value

Legend visibility, specified as "on" or "off", or as numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

When you set this property to "on", the legend is visible in the chart.

LegendTitle — Legend title

string | character vector | cell array of character vectors | categorical array

Legend title, specified as a string, character vector, cell array of character vectors, or categorical array. To create a multiline title, specify a string array or cell array of character vectors. Each element in the array is a separate line of text.

Color and Styling

ColorOrder — Color order

seven predefined colors (default) | three-column matrix of RGB triplets

Color order, specified as a three-column matrix of RGB triplets. This property defines the palette of colors MATLAB uses to create the chart. Each row of the matrix is an RGB triplet. An RGB triplet is a three-element vector whose elements specify the intensities of the red, green, and blue components of a color. The intensities must be in the range [0, 1]. This table lists the default pallet of colors.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

Note

As an alternative, you can set this property and access several predefined color palettes by passing the PieChart object to the colororder function.

FaceColor — Slice colors

"flat" (default) | RGB triplet | hexadecimal color code | color name | short name | "none"

Slice colors, specified as a value from this table.

FaceColor Value	Description
"flat"	Let MATLAB assign a different color to each slice. The colors are defined in the ColorOrder property of the chart.
RGB triplet or hexadecimal color code	Assign one custom color to all the slices: RGB triplet — A three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. Hexadecimal color code — A character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent. The two tables below provide the RGB triplets and hexadecimal color codes for some common colors.
Color name or short name	Assign one named color to all the slices using a color name such as "red", or a short name such as "r". The table below lists the available color names and short names.
"none"	Display all the slices without any color.

This table lists the available color names and short names with corresponding RGB triplets and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

EdgeColor — Slice outline color

[0.15 0.15 0.15] (default) | "flat" | RGB triplet | hexadecimal color code | color name | short name | "none"

Slice outline color, specified as a value from this table.

EdgeColor Value	Description
"flat"	Let MATLAB assign a different outline color to each slice. The colors are defined in the ColorOrder property of the chart.
RGB triplet or hexadecimal color code	Assign one custom outline color to all the slices: RGB triplet — A three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. Hexadecimal color code — A character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent. The two tables below provide the RGB triplets and hexadecimal color codes for some common colors.
Color name or short name	Assign one named outline color to all the slices using a color name such as "red", or a short name such as "r". The table below lists the available color names and short names.
"none"	Display the chart without any outline color.

This table lists the available color names and short names with corresponding RGB triplets and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

FaceAlpha — Slice fill color transparency

0.60 (default) | scalar in range [0,1]

Slice fill color transparency, specified as a scalar in the range [0,1]. A value of 1 makes the slices opaque, and 0 makes them completely transparent. Values between 0 and 1 make the slices partially transparent.

LineWidth — Thickness of slice outlines

0.5 (default) | positive value

Thickness of slice outlines, specified as a positive value in points.

ExplodedWedges — Offset slices

numeric vector | logical vector | string vector | character vector

Offset slices, specified as a numeric or logical vector for numeric data. If you create the chart using categorical data, you can specify a string vector or a character vector containing one or more category names. The orange slice in this pie chart is offset.

Example: piechart([5 7 4 6],ExplodedWedges=3) creates a pie chart with the third slice offset.

Example: piechart([5 7 4 6],ExplodedWedges=[1 3]) creates a pie chart with the first and third slice offset.

Example: piechart([5 7 4 6],ExplodedWedges=[false false true false]) creates a pie chart with the third slice offset.

Example: piechart(categorical(["A" "B" "C" "D"]),ExplodedWedges="B") creates a pie chart using categorical data with slice B offset.

Direction — Direction for adding slices

"clockwise" (default) | "counterclockwise"

Direction for adding slices, specified as "clockwise" or "counterclockwise".

• "clockwise" — Add slices in a clockwise direction.

• "counterclockwise" — Add slices in a counterclockwise direction.

Data Display

CategoryCounts — Category counts

numeric vector

This property is read-only.

Category counts when you specify categorical data, returned as a numeric vector. The number of elements in the vector is the number of categories in your data. Each element of the vector contains the number of instances of a category.

StartAngle — Starting angle of first slice

0 (default) | number in degrees

Starting angle of the first slice, specified as a scalar value in degrees. By default, the starting angle is 0 degrees. Positive values rotate the slices in a clockwise direction. Negative values rotate the slices in a counterclockwise direction.

You can envision the location of the starting angle by considering the arrangement of numbers on a clock. A starting angle of 0 degrees corresponds to 12 o'clock, and a starting angle of 90 degrees corresponds to 3 o'clock.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Proportions — Slice proportions

numeric vector

This property is read-only.

Slice proportions, returned as a numeric vector containing the size of each slice as a proportion out of 1. If you create the chart using categorical data, then the proportions are the CategoryCounts divided by the number of categories.

Font

FontName — Font name

supported font name | "FixedWidth"

Font name, specified as a supported font name or "FixedWidth". To display and print text properly, you must choose a font that your system supports. The default font depends on your operating system and locale.

To use a fixed-width font that looks good in any locale, use "FixedWidth". The fixed-width font relies on the root FixedWidthFontName property. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

FontSize — Font size

scalar value greater than zero

Font size, specified as a scalar value greater than zero in point units. The default font size depends on the specific operating system and locale. One point equals 1/72 inch.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

FontSizeMode — How font size is selected

"auto" (default) | "manual"

How font size is selected, specified as "auto" or "manual".

• "auto" — MATLAB selects the font size automatically and scales the text slightly according to the size of the chart, which typically changes when you resize the figure.

• "manual" — You set the font size, and it remains unchanged regardless of the size of the chart.

FontColor — Font color

RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Font color, specified as an RGB triplet, a hexadecimal color code, or one of the options listed in the table.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

Vector Data

Data — Slice data

numeric vector | duration vector | categorical vector | logical vector

Slice data, specified as a vector of numeric, duration, categorical, or logical values.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | duration | categorical | logical

DataMode — How Data is set

"auto" | "manual"

How the Data property is set, specified as one of these values:

• "auto" — The Data property updates automatically based on the SourceTable and DataVariable properties. This is the case when you pass a table to the piechart or donutchart functions.

• "manual" — The Data property is set directly and does not update automatically. This is the case when you pass data values as a vector to the piechart or donutchart functions.

Names — Slice names

string vector | cell array of character vectors

Slice names, specified as a string vector or cell array of character vectors.

The default slice names, and whether you can change them, depend on how you create your chart:

• If you create the chart with numeric or duration data without specifying the slice names, the Names property contains the string vector ["data1","data2",…,"dataN"]. However, the slice labels do not include those default names. If you set the Names property explicitly, then the slice labels include the names.

• If you create the chart with categorical data, then the Names property contains the category names, and you cannot change them. In this case, the slice labels include the category names, and you can change the slice labels by setting the Labels property.

• If you create the chart with a table and specify the namesvar input argument, then the Names property contains the names from that table variable, and you cannot set the Names property directly. If you do not specify the namesvar argument when you create the chart, you can set the Names property.

NamesMode — How Names is set

"auto" | "manual"

How the Names property is set, specified as one of these values:

• "auto" — MATLAB controls the value of the Names property. The Names value can be:

  • The string vector ["data1","data2",…,"dataN"] for N slices.

  • A string vector of category names.

  • The values in a table variable. The SourceTable property specifies the table, and the NamesVariable property specifies the variable. If either the SourceTable or NamesVariableproperty is empty, then the Names property contains ["data1","data2",…,"dataN"] instead.

• "manual" — The Names property is set directly and does not update automatically. This is the case when you pass the slice names as a vector (such as a string or numeric vector) to the piechart or donutchart functions.

Table Data

SourceTable — Source table

table | timetable

Source table containing the chart data. Specify this property as a table or a timetable.

DataVariable — Table variable containing slice data

string scalar | character vector | pattern | numeric scalar | logical vector | vartype()

Table variable containing the slice data, specified using one of the indexing schemes from the following table. The variable you specify can contain numeric, duration, categorical, or logical values. When you set this property, MATLAB updates the Data property. The SourceTable property must contain a table with at least one variable. Otherwise, this property has no effect.

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A pattern object. The pattern object must refer to only one variable.	"A" or 'A' — A variable named A "Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.	3 — The third variable from the table [false false true] — The third variable
Variable type: A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	vartype("double") — The variable containing double values

NamesVariable — Table variable containing slice names

string scalar | character vector | pattern | numeric scalar | logical vector | vartype()

Table variable containing the slice names, specified using one of the indexing schemes from the following table. The variable you specify can contain a string vector, a cell array of character vectors, or a vector of numeric, datetime, duration, or categorical values. When you set this property, MATLAB updates the Names property. The SourceTable property must contain a table with at least one variable. Otherwise, this property has no effect.

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A pattern object. The pattern object must refer to only one variable.	"A" or 'A' — A variable named A "Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.	3 — The third variable from the table [false false true] — The third variable
Variable type: A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	vartype("double") — The variable containing double values

Position

OuterPosition — Outer size and location

[0 0 1 1] (default) | four-element vector

Outer size and location of the chart within the parent container (typically a figure, panel, or tiled chart layout), specified as a four-element vector of the form [left bottom width height]. The outer size and location includes the legend and title.

• The left and bottom elements define the distance from the lower-left corner of the container to the lower-left corner of the chart.

• The width and height elements are the chart dimensions, which include a margin for the surrounding legend and title.

The default value of [0 0 1 1] covers the whole interior of the container. The units are normalized relative to the size of the container. To change the units, set the Units property.

Note

Setting this property has no effect when the parent container is a TiledChartLayout object.

InnerPosition — Inner size and location

four-element vector

Inner size and location of the chart within the parent container (typically a figure, panel, or tiled chart layout) specified as a four-element vector of the form [left bottom width height]. The inner size and location does not include the legend or title.

• The left and bottom elements define the distance from the lower-left corner of the container to the lower-left corner of the box that encloses the chart.

• The width and height elements are the dimensions of the box that encloses the chart.

Note

Setting this property has no effect when the parent container is a TiledChartLayout object.

Position — Inner size and location

four-element vector

Inner size and location of the chart within the parent container (typically a figure, panel, or tiled chart layout), specified as a four-element vector of the form [left bottom width height]. This property is equivalent to the InnerPosition property.

Note

Setting this property has no effect when the parent container is a TiledChartLayout object.

PositionConstraint — Position to hold constant

"outerposition" | "innerposition"

Position property to hold constant when adding, removing, or changing decorations, specified as one of the following values:

• "outerposition" — The OuterPosition property remains constant when you add, remove, or change decorations such as a title or an axis label. If any positional adjustments are needed, MATLAB adjusts the InnerPosition property.

• "innerposition" — The InnerPosition property remains constant when you add, remove, or change decorations such as a title or an axis label. If any positional adjustments are needed, MATLAB adjusts the OuterPosition property.

Note

Setting this property has no effect when the parent container is a TiledChartLayout object.

Units — Position units

"normalized" (default) | "inches" | "centimeters" | "characters" | "points" | "pixels"

Position units, specified as one of the values in this table.

Units	Description
"normalized" (default)	Normalized with respect to the container, which is typically the figure or a panel. The lower-left corner of the container maps to (0,0), and the upper-right corner maps to (1,1).
"inches"	Inches.
"centimeters"	Centimeters.
"characters"	Based on the default font of the graphics root object: Character width = width of letter x. Character height = distance between the baselines of two lines of text.
"points"	Typography points. One point equals 1/72 inch.
"pixels"	Pixels. Distances in pixels are independent of your system resolution on Windows® and Macintosh systems: On Windows systems, a pixel is 1/96 of an inch. On Macintosh systems, a pixel is 1/72 of an inch. On Linux® systems, the size of a pixel is determined by your system resolution.

When specifying the units as a name-value pair during object creation, you must set the Units property before specifying the properties that you want to use these units, such as OuterPosition.

Layout — Layout options

empty LayoutOptions array (default) | TiledChartLayoutOptions object | GridLayoutOptions object

Layout options, specified as a TiledChartLayoutOptions or GridLayoutOptions object. This property is useful when the chart is either in a tiled chart layout or a grid layout.

To position the chart within the grid of a tiled chart layout, set the Tile and TileSpan properties on the TiledChartLayoutOptions object. For example, consider a 3-by-3 tiled chart layout. The layout has a grid of tiles in the center, and four tiles along the outer edges. In practice, the grid is invisible and the outer tiles do not take up space until you populate them with axes or charts.

This code places the chart c in the third tile of the grid.

c.Layout.Tile = 3;

To make the chart span multiple tiles, specify the TileSpan property as a two-element vector. For example, this chart spans 2 rows and 3 columns of tiles.

c.Layout.TileSpan = [2 3];

To place the chart in one of the surrounding tiles, specify the Tile property as "north", "south", "east", or "west". For example, setting the value to "east" places the chart in the tile to the right of the grid.

c.Layout.Tile = "east";

To place the chart into a layout within an app, specify this property as a GridLayoutOptions object. For more information about working with grid layouts in apps, see uigridlayout.

If the chart is not a child of either a tiled chart layout or a grid layout (for example, if it is a child of a figure or panel) then this property is empty and has no effect.

Visible — State of visibility

"on" (default) | on/off logical value

State of visibility, specified as "on" or "off", or as numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• "on" — Display the chart.

• "off" — Hide the chart without deleting it. You still can access the properties of an invisible PieChart object.

Parent/Child

Parent — Parent container

Figure object | Panel object | Tab object | TiledChartLayout object | GridLayout object

Parent container, specified as a Figure, Panel, Tab, TiledChartLayout, or GridLayout object.

Version History

Introduced in R2023b

R2024a: Change slice labels with minimal code

You can specify different slice labels by setting the LabelStyle property.