Main Content

DonutChart Properties

Donut chart appearance and behavior

Since R2023b

DonutChart properties control the appearance and behavior of donut charts. By changing property values, you can modify certain aspects of a chart. Use dot notation to query and set properties.

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

Labels

expand all

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

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.

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

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.

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

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 TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Note

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

Slice colors, specified as a value from this table.

FaceColor ValueDescription
"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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

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

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

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

EdgeColor ValueDescription
"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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

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

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

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.

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

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.

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

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.

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.

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

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

expand all

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.

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

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.

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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

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

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Vector Data

expand all

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

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.

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.

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

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

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 SchemeExamples

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

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 SchemeExamples

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

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.

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.

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.

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.

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

UnitsDescription
"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 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.

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 container, specified as a Figure, Panel, Tab, TiledChartLayout, or GridLayout object.

Version History

Introduced in R2023b

See Also

Functions