DonutChart Properties

Labels

`Title` — Chart title
string vector | character vector | cell array of character vectors | categorical array

Chart title, specified as a character vector, cell array of character vectors, string vector, or categorical array. To create a multiline title, specify a string vector or a 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.

donutchart([1 2 3 4])
title("My Donut 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"` | `"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 donut 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.

`CenterLabel` — Center label
`""` (default) | string vector | character vector | cell array of character vectors

Since R2024a

Center label, specified as a string vector, character vector, or cell array of character vectors. To create a multiline label, specify a string vector or cell array of character vectors, where each element is a line of text.

For example, create a donut chart with a center label containing two lines of text.

d = donutchart([0.6 1.8 1.3 0.9 0.4],["Rent" "Payroll" "COGS" "Taxes" "Interest"]);
d.CenterLabel = ["Expenses" "$5M"];

Donut chart with a center label on two lines. "Expenses" is on the first line, and "$5M" is on the second line.

`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

expand all

`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 DonutChart 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
`"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
`"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.

`InnerRadius` — Inner radius
`0.6` (default) | scalar in range [0, 1].

Inner radius, specified as a scalar in the range [0, 1]. A value of 0 creates a pie chart with no hole, and a value of 1 creates a thin ring with no apparent slices.

Comparison of three donut charts with different inner radius values. Smaller values create smaller holes with thicker donut walls, and larger values create larger holes with thinner donut walls.

`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 donut chart is offset.

Donut chart with the second slice offset

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

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

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

Example: donutchart(categorical(["A" "B" "C" "D"]),ExplodedWedges="B") creates a donut 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

expand all

`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.

Two donut charts with different starting angles. One chart has a starting angle of 0 degrees, and the other chart has a starting angle of 90 degrees.

`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.

`DisplayOrder` — Slice display order
`"data"` (default) | `"ascend"` | `"descend"`

Since R2024b

Slice display order, specified as one of the values in this table. By default, the first slice is positioned according to the StartAngle property, and subsequent slices follow clockwise or counterclockwise depending on the Direction property.

Value Description Example with Data=[3 2 4 1]

Value	Description	Example with `Data=[3 2 4 1]`
`"data"`	Order of the values in the `Data` property
`"ascend"`	Ascending order
`"descend"`	Descending order

"data"

Order of the values in the Data property

Donut chart with slices arranged in the same order as the Data property

"ascend"

Ascending order

Donut chart with slices arranged in ascending order

"descend"

Descending order

Donut chart with slices arranged in descending order

`NumDisplayWedges` — Number of slices to display
`Inf` (default) | positive whole number

Since R2024b

Number of slices to display in the chart, specified as a positive whole number. By default, the chart displays all the data values using as many slices as needed. If you specify a number n that is less than Inf, and your data contains more than n values, the sum of the remaining values is displayed in an additional slice named "Others". To hide the "Others" slice, set the ShowOthers property to "off".

`ShowOthers` — Show `"Others"` slice
`"on"` (default) | on/off logical value

Since R2024b

Show the "Others" slice, 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" — If the NumDisplayWedges property is less than the number of values in the Data property, the chart displays an additional slice named "Others" that represents the sum of the remaining values. If you create the chart with a categorical array that contains <undefined> values, then the chart includes the <undefined> values in the "Others" slice.
"off" — Show only the number of slices specified by NumDisplayWedges. If NumDisplayWedges is Inf, show one slice for each data value that is not <undefined>.

`WedgeDisplayData` — Data values of displayed slices
numeric vector

Since R2024b

This property is read-only.

Data values of the displayed slices, returned as a numeric vector. The vector contains one element per slice in the order they appear in the chart.

`WedgeDisplayNames` — Names of displayed slices
string vector

Since R2024b

This property is read-only.

Names of the displayed slices, returned as a string vector. The vector contains one element per slice in the order they appear in the chart.

Font

expand all

`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.

`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.

`CenterLabelFontSize` — Center label font size
scalar value greater than zero

Since R2024a

Center label font size, specified as a scalar value greater than zero in point units. One point equals 1/72 inch.

`CenterLabelFontSizeMode` — How center label font size is selected
`"auto"` (default) | `"manual"`

Since R2024a

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

"auto" — MATLAB calculates the font size according to the inner radius of the chart.
"manual" — You specify the font size by setting the CenterLabelFontSize property.

`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
`"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

expand all

`Data` — Slice data
numeric vector | duration vector | categorical vector | logical vector

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

`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

expand all

`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

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

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

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

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

expand all

`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 argument 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.

Diagram of a 3-by-3 tiled chart layout.

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 DonutChart object.

Parent/Child

expand all

`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

expand all

R2024b: Control number of slices and slice order

Simplify donut charts with large numbers of slices by setting properties that control the order and number of slices. Use the DisplayOrder property to arrange slices from largest to smallest and use the NumDisplayWedges property to specify the number of slices to display separately (the remaining slice data is grouped together as a slice labeled "Others").

Other useful properties include:

ShowOthers — Show a slice labeled "Others" to represent values not shown as individual slices. For example, <undefined> categorical values are represented in the "Others" slice.
WedgeDisplayNames — Return the labels of the slices shown in the chart.
WedgeDisplayData — Return the data values for slices shown in the chart.

R2024a: Create center label

Summarize your data by creating a label in the center of your chart. Set the CenterLabel property to create the label, and set the CenterLabelFontSize property to modify the font size of the label.

R2024a: Change slice labels with minimal code

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

DonutChart Properties

Labels

Title — Chart title string vector | character vector | cell array of character vectors | categorical array

Labels — Slice labels string vector | cell array of character vectors

LabelsMode — How slices are labeled "auto" | "manual"

LabelStyle — Label style "namepercent" | "namedata" | "name" | "data" | "percent" | "none"

LabelStyleMode — How label style is selected "auto" (default) | "manual"

CenterLabel — Center label "" (default) | string vector | character vector | cell array of character vectors

LegendVisible — Legend visibility "off" (default) | on/off logical value

LegendTitle — Legend title string | character vector | cell array of character vectors | categorical array

Color and Styling

ColorOrder — Color order seven predefined colors (default) | three-column matrix of RGB triplets

FaceColor — Slice colors "flat" (default) | RGB triplet | hexadecimal color code | color name | short name | "none"

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

FaceAlpha — Slice fill color transparency 0.60 (default) | scalar in range [0,1]

LineWidth — Thickness of slice outlines 0.5 (default) | positive value

InnerRadius — Inner radius 0.6 (default) | scalar in range [0, 1].

ExplodedWedges — Offset slices numeric vector | logical vector | string vector | character vector

Direction — Direction for adding slices "clockwise" (default) | "counterclockwise"

Data Display

CategoryCounts — Category counts numeric vector

StartAngle — Starting angle of first slice 0 (default) | number in degrees

Proportions — Slice proportions numeric vector

DisplayOrder — Slice display order "data" (default) | "ascend" | "descend"

NumDisplayWedges — Number of slices to display Inf (default) | positive whole number

ShowOthers — Show "Others" slice "on" (default) | on/off logical value

WedgeDisplayData — Data values of displayed slices numeric vector

WedgeDisplayNames — Names of displayed slices string vector

Font

FontName — Font name supported font name | "FixedWidth"

FontSize — Font size scalar value greater than zero

FontSizeMode — How font size is selected "auto" (default) | "manual"

CenterLabelFontSize — Center label font size scalar value greater than zero

CenterLabelFontSizeMode — How center label font size is selected "auto" (default) | "manual"

FontColor — Font color RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Vector Data

Data — Slice data numeric vector | duration vector | categorical vector | logical vector

DataMode — How Data is set "auto" | "manual"

Names — Slice names string vector | cell array of character vectors

NamesMode — How Names is set "auto" | "manual"

Table Data

SourceTable — Source table table | timetable

DataVariable — Table variable containing slice data string scalar | character vector | pattern | numeric scalar | logical vector | vartype()

NamesVariable — Table variable containing slice names string scalar | character vector | pattern | numeric scalar | logical vector | vartype()

Position

OuterPosition — Outer size and location [0 0 1 1] (default) | four-element vector

InnerPosition — Inner size and location four-element vector

Position — Inner size and location four-element vector

PositionConstraint — Position to hold constant "outerposition" | "innerposition"

Units — Position units "normalized" (default) | "inches" | "centimeters" | "characters" | "points" | "pixels"

Layout — Layout options empty LayoutOptions array (default) | TiledChartLayoutOptions object | GridLayoutOptions object

Visible — State of visibility "on" (default) | on/off logical value

Parent/Child

Parent — Parent container Figure object | Panel object | Tab object | TiledChartLayout object | GridLayout object

Version History

R2024b: Control number of slices and slice order

R2024a: Create center label

R2024a: Change slice labels with minimal code

See Also

Functions

`Title` — Chart title
string vector | character vector | cell array of character vectors | categorical array

`Labels` — Slice labels
string vector | cell array of character vectors

`LabelsMode` — How slices are labeled
`"auto"` | `"manual"`

`LabelStyle` — Label style
`"namepercent"` | `"namedata"` | `"name"` | `"data"` | `"percent"` | `"none"`

`LabelStyleMode` — How label style is selected
`"auto"` (default) | `"manual"`

`CenterLabel` — Center label
`""` (default) | string vector | character vector | cell array of character vectors

`LegendVisible` — Legend visibility
`"off"` (default) | on/off logical value

`LegendTitle` — Legend title
string | character vector | cell array of character vectors | categorical array

`ColorOrder` — Color order
seven predefined colors (default) | three-column matrix of RGB triplets

`FaceColor` — Slice colors
`"flat"` (default) | RGB triplet | hexadecimal color code | color name | short name | `"none"`

`EdgeColor` — Slice outline color
`[0.15 0.15 0.15]` (default) | `"flat"` | RGB triplet | hexadecimal color code | color name | short name | `"none"`

`FaceAlpha` — Slice fill color transparency
`0.60` (default) | scalar in range `[0,1]`

`LineWidth` — Thickness of slice outlines
`0.5` (default) | positive value

`InnerRadius` — Inner radius
`0.6` (default) | scalar in range [0, 1].

`ExplodedWedges` — Offset slices
numeric vector | logical vector | string vector | character vector

`Direction` — Direction for adding slices
`"clockwise"` (default) | `"counterclockwise"`

`CategoryCounts` — Category counts
numeric vector

`StartAngle` — Starting angle of first slice
`0` (default) | number in degrees

`Proportions` — Slice proportions
numeric vector

`DisplayOrder` — Slice display order
`"data"` (default) | `"ascend"` | `"descend"`

`NumDisplayWedges` — Number of slices to display
`Inf` (default) | positive whole number

`ShowOthers` — Show `"Others"` slice
`"on"` (default) | on/off logical value

`WedgeDisplayData` — Data values of displayed slices
numeric vector

`WedgeDisplayNames` — Names of displayed slices
string vector

`FontName` — Font name
supported font name | `"FixedWidth"`

`FontSize` — Font size
scalar value greater than zero

`FontSizeMode` — How font size is selected
`"auto"` (default) | `"manual"`

`CenterLabelFontSize` — Center label font size
scalar value greater than zero

`CenterLabelFontSizeMode` — How center label font size is selected
`"auto"` (default) | `"manual"`

`FontColor` — Font color
RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

`Data` — Slice data
numeric vector | duration vector | categorical vector | logical vector

`DataMode` — How `Data` is set
`"auto"` | `"manual"`

`Names` — Slice names
string vector | cell array of character vectors

`NamesMode` — How `Names` is set
`"auto"` | `"manual"`

`SourceTable` — Source table
table | timetable

`DataVariable` — Table variable containing slice data
string scalar | character vector | pattern | numeric scalar | logical vector | `vartype()`

`NamesVariable` — Table variable containing slice names
string scalar | character vector | pattern | numeric scalar | logical vector | `vartype()`

`OuterPosition` — Outer size and location
`[0 0 1 1]` (default) | four-element vector

`InnerPosition` — Inner size and location
four-element vector

`Position` — Inner size and location
four-element vector

`PositionConstraint` — Position to hold constant
`"outerposition"` | `"innerposition"`

`Units` — Position units
`"normalized"` (default) | `"inches"` | `"centimeters"` | `"characters"` | `"points"` | `"pixels"`

`Layout` — Layout options
empty `LayoutOptions` array (default) | `TiledChartLayoutOptions` object | `GridLayoutOptions` object

`Visible` — State of visibility
`"on"` (default) | on/off logical value

`Parent` — Parent container
`Figure` object | `Panel` object | `Tab` object | `TiledChartLayout` object | `GridLayout` object