Axes - Axes appearance and behavior - MATLAB (original) (raw)

Axes Properties

Axes appearance and behavior

Axes properties control the appearance and behavior of an Axes object. By changing property values, you can modify certain aspects of the axes. Use dot notation to query and set properties.

ax = gca; c = ax.Color; ax.Color = 'blue';

Font

expand all

Font size, specified as a scalar numeric value. The font size affects the title, axis labels, and tick labels. It also affects any legends or colorbars associated with the axes. The default font size depends on the specific operating system and locale. By default, the font size is measured in points. To change the units, set the FontUnits property.

MATLAB automatically scales some of the text to a percentage of the axes font size.

Example: ax.FontSize = 12

Selection mode for the font size, specified as one of these values:

Scale factor for the label font size, specified as a numeric value greater than 0. The scale factor is applied to the value of theFontSize property to determine the font size for the _x_-axis, _y_-axis, and_z_-axis labels.

Example: ax.LabelFontSizeMultiplier = 1.5

Scale factor for the title font size, specified as a numeric value greater than 0. The scale factor is applied to the value of the FontSize property to determine the font size for the title.

Subtitle character thickness, specified as one of these values:

Ticks

expand all

Tick values, specified as a vector of increasing values. If you do not want tick marks along the axis, then specify an empty vector[]. The tick values are the locations along the axis where the tick marks appear. The tick labels are the labels that you see next to each tick mark. Use the XTickLabels,YTickLabels, and ZTickLabels properties to specify the associated labels.

Example: ax.XTick = [2 4 6 8 10]

Example: ax.YTick = 0:10:100

Alternatively, use the xticks, yticks, and zticks functions to specify the tick values. For an example, see Specify Axis Tick Values and Labels.

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

Selection mode for the tick values, specified as one of these values:

Example: ax.XTickMode = 'auto'

Tick labels, specified as a cell array of character vectors, string array, or categorical array. If you do not want tick labels to show, then specify an empty cell array {}. If you do not specify enough labels for all the tick values, then the labels repeat.

Tick labels support TeX and LaTeX markup. See the TickLabelInterpreter property for more information.

If you specify this property as a categorical array, MATLAB uses the values in the array, not the categories.

As an alternative to setting this property, you can use the xticklabels, yticklabels, and zticklabels functions. For an example, see Specify Axis Tick Values and Labels.

Example: ax.XTickLabel = {'Jan','Feb','Mar','Apr'}

Selection mode for the tick labels, specified as one of these values:

Example: ax.XTickLabelMode = 'auto'

Tick label rotation, specified as a numeric value in degrees. Positive values give counterclockwise rotation. Negative values give clockwise rotation.

Example: ax.XTickLabelRotation = 45

Example: ax.YTickLabelRotation = 90

Alternatively, use the xtickangle, ytickangle, and ztickangle functions.

Selection mode for the tick label rotation, specified as one of these values:

Minor tick marks, 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.

Example: ax.XMinorTick = 'on'

Tick mark direction, specified as one of these values:

Tick mark length, specified as a two-element vector of the form[2Dlength 3Dlength]. The first element is the tick mark length in 2-D views and the second element is the tick mark length in 3-D views. Specify the values in units normalized relative to the longest of the visible _x_-axis, _y_-axis, or_z_-axis lines.

Example: ax.TickLength = [0.02 0.035]

Rulers

expand all

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

Selection mode for the axis limits, specified as one of these values:

Example: ax.XLimMode = 'auto'

Axis limit selection method, specified as a value from the table. The examples in the table show the approximate appearance for different values of the XLimitMethod property. Your results might differ depending on your data, the size of the axes, and the type of plot you create.

Value Description Example (XLimitMethod)
'tickaligned' In general, align the edges of the axes box with the tick marks that are closest to your data without excluding any data. The appearance might vary depending on the type of data you plot and the type of chart you create. Plotted sine wave with XLimitMethod set to 'tickaligned'.
'tight' Fit the axes box tightly around the data by setting the axis limits equal to the range of the data. Plotted sine wave with XLimitMethod set to 'tight'.
'padded' Fit the axes box around the data with a thin margin of padding on each side. The width of the margin is approximately 7% of your data range. Plotted sine wave with XLimitMethod set to 'padded'.

Note

The axis limit method has no effect when the corresponding mode property (XLimMode, YLimMode, or ZLimMode) is set to 'manual'.

Axis ruler, returned as a ruler object. The ruler controls the appearance and behavior of the _x_-axis,_y_-axis, or _z_-axis. Modify the appearance and behavior of a particular axis by accessing the associated ruler and setting ruler properties. The type of ruler that MATLAB creates for each axis depends on the plotted data. For a list of ruler properties that Axes objects support, see:

For example, access the ruler for the _x_-axis through the XAxis property. Then, change theColor property of the ruler, and thus the color of the _x_-axis, to red. Similarly, change the color of the_y_-axis to green.

ax = gca; ax.XAxis.Color = 'r'; ax.YAxis.Color = 'g';

If the Axes object has two _y_-axes, then theYAxis property stores two ruler objects.

_x_-axis location, specified as one of the values in this table. This property applies only to 2-D views.

Value Description Result
'bottom' Bottom of the axes. Example: ax.XAxisLocation = 'bottom' Empty axes with the x-axis at the bottom.
'top' Top of the axes. Example: ax.XAxisLocation = 'top' Empty axes with the x-axis at the top.
'origin' Through the origin point (0,0). Example: ax.XAxisLocation = 'origin' Empty axes with the x-axis at the origin.

_y_-axis location, specified as one of the values in this table. This property applies only to 2-D views.

Value Description Result
'left' Left side of the axes. Example: ax.YAxisLocation = 'left' Empty axes with the y-axis on the left.
'right' Right side of the axes. Example: ax.YAxisLocation = 'right' Empty axes with the y-axis on the right.
'origin' Through the origin point (0,0). Example: ax.YAxisLocation = 'origin' Empty axes with the y-axis at the origin.

Color of the axis line, tick values, and labels in the_x_, y, or_z_ direction, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name. The color you specify also affects the grid lines, unless you specify the grid line color using the GridColor or MinorGridColor property.

For a custom color, specify an RGB triplet or a hexadecimal color code.

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

Color Name Short Name RGB Triplet Hexadecimal Color Code Appearance
"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
"none" Not applicable Not applicable Not applicable No color

This table lists the default color palettes for plots in the light and dark themes.

Palette Palette Colors
"gem" — Light theme default_Before R2025a: Most plots use these colors by default._ Sample of the "gem" color palette
"glow" — Dark theme default Sample of the "glow" color palette

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem"); H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Example: ax.XColor = [1 1 0]

Example: ax.YColor = 'y'

Example: ax.ZColor = 'yellow'

Example: ax.ZColor = '#FFFF00'

Property for setting the _x_-axis grid color, specified as 'auto' or 'manual'. The mode value only affects the _x_-axis grid color. The_x_-axis line, tick values, and labels always use theXColor value, regardless of the mode.

The _x_-axis grid color depends on both theXColorMode property and theGridColorMode property, as shown here.

XColorMode GridColorMode x-Axis Grid Color
'auto' 'auto' GridColor property
'manual' GridColor property
'manual' 'auto' XColor property
'manual' GridColor property

The _x_-axis minor grid color depends on both theXColorMode property and theMinorGridColorMode property, as shown here.

XColorMode MinorGridColorMode x-Axis Minor Grid Color
'auto' 'auto' MinorGridColor property
'manual' MinorGridColor property
'manual' 'auto' XColor property
'manual' MinorGridColor property

Property for setting the _y_-axis grid color, specified as 'auto' or 'manual'. The mode value only affects the _y_-axis grid color. The_y_-axis line, tick values, and labels always use theYColor value, regardless of the mode.

The _y_-axis grid color depends on both theYColorMode property and theGridColorMode property, as shown here.

YColorMode GridColorMode y-Axis Grid Color
'auto' 'auto' GridColor property
'manual' GridColor property
'manual' 'auto' YColor property
'manual' GridColor property

The _y_-axis minor grid color depends on both theYColorMode property and theMinorGridColorMode property, as shown here.

YColorMode MinorGridColorMode y-Axis Minor Grid Color
'auto' 'auto' MinorGridColor property
'manual' MinorGridColor property
'manual' 'auto' YColor property
'manual' MinorGridColor property

Property for setting the _z_-axis grid color, specified as 'auto' or 'manual'. The mode value only affects the _z_-axis grid color. The_z_-axis line, tick values, and labels always use theZColor value, regardless of the mode.

The _z_-axis grid color depends on both theZColorMode property and theGridColorMode property, as shown here.

ZColorMode GridColorMode z-Axis Grid Color
'auto' 'auto' GridColor property
'manual' GridColor property
'manual' 'auto' ZColor property
'manual' GridColor property

The _z_-axis minor grid color depends on both theZColorMode property and theMinorGridColorMode property, as shown here.

ZColorMode MinorGridColorMode z-Axis Minor Grid Color
'auto' 'auto' MinorGridColor property
'manual' MinorGridColor property
'manual' 'auto' ZColor property
'manual' MinorGridColor property

_x_-axis direction, specified as one of these values.

Value Description Result in 2-D Result in 3-D
'normal' Values increase from left to right.Example: ax.XDir = 'normal' 2-D axes with the x-axis direction set to 'normal'. The tick values for the x-axis increase from left to right. 3-D axes with the x-axis direction set to 'normal'. If you look at the x-y plane, the x-axis tick values increase from left to right.
'reverse' Values increase from right to left.Example: ax.XDir = 'reverse' 2-D axes with the x-axis direction set to 'reverse'. The tick values for the x-axis increase from right to left. 3-D axes with the x-axis direction set to 'reverse'. If you look at the x-y plane, the x-axis tick values increase from right to left.

_y_-axis direction, specified as one of these values.

Value Description Result in 2-D Result in 3-D
'normal' Values increase from bottom to top (2-D view) or front to back (3-D view).Example: ax.YDir = 'normal' 2-D axes with the y-axis direction set to 'normal'. The tick values for the y-axis increase from bottom to top. 3-D axes with the y-axis direction set to 'normal'. If you look at the x-y plane, the y-axis tick values increase from bottom to top.
'reverse' Values increase from top to bottom (2-D view) or back to front (3-D view).Example: ax.YDir = 'reverse' 2-D axes with the y-axis direction set to 'reverse'. The tick values for the y-axis increase from top to bottom. 3-D axes with the y-axis direction set to 'reverse'. If you look at the x-y plane, the y-axis tick values increase from top to bottom.

_z_-axis direction, specified as one of these values.

Value Description Result in 3-D
'normal' Values increase pointing out of the screen (2-D view) or from bottom to top (3-D view).Example: ax.ZDir = 'normal' 3-D axes with the z-axis direction set to 'normal'. If the z-axis is the vertical axis, its tick values increase from bottom to top.
'reverse' Values increase pointing into the screen (2-D view) or from top to bottom (3-D view).Example: ax.ZDir = 'reverse' 3-D axes with the z-axis direction set to 'reverse'. If the z-axis is the vertical axis, its tick values increase from top to bottom.

Grids

expand all

Grid lines, 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.

Alternatively, use the grid on or grid off command to set all three properties to'on' or 'off', respectively. For more information, see grid.

Example: ax.XGrid = 'on'

Since R2023a

Grid line width, specified as a positive number. Set this property or the MinorGridLineWidth property to control the thickness of the grid lines independently of the box outline and tick marks.

Example

Create vectors x and y, and plot them. Display the grid lines in the axes by calling grid on. Increase the thickness of the grid lines, box outline, and tick marks by setting theLineWidth property of the axes to1.5.

x = linspace(0,10); y = sin(x); plot(x,y) grid on ax = gca; ax.LineWidth = 1.5;

Line plot with a thick box outline, thick tick marks, and thick grid lines

Make the grid lines thinner by setting the grid line width to 0.5.

Updated plot with thin grid lines, but with the same thick box outline and thick tick marks

Since R2023a

How the grid line width is set, specified as one of these values:

MATLAB sets this property to "manual" when you explicitly set the GridLineWidth property to a value.

Color of grid lines, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

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

Color Name Short Name RGB Triplet Hexadecimal Color Code Appearance
"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
"none" Not applicable Not applicable Not applicable No color

This table lists the default color palettes for plots in the light and dark themes.

Palette Palette Colors
"gem" — Light theme default_Before R2025a: Most plots use these colors by default._ Sample of the "gem" color palette
"glow" — Dark theme default Sample of the "glow" color palette

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem"); H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

To set the colors for the axes box outline, use theXColor, YColor, andZColor properties.

To display the grid lines, use the grid on command or set the XGrid, YGrid, orZGrid property to 'on'.

Example: ax.GridColor = [0 0 1]

Example: ax.GridColor = 'b'

Example: ax.GridColor = 'blue'

Example: ax.GridColor = '#0000FF'

Property for setting the grid color, specified as one of these values:

Minor grid lines, 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.

Alternatively, use the grid minor command to toggle the visibility of the minor grid lines.

Example: ax.XMinorGrid = 'on'

Line style for minor grid lines, specified as one of the line styles shown in this table.

Line Style Description Resulting Line
"-" Solid line Sample of solid line
"--" Dashed line Sample of dashed line
":" Dotted line Sample of dotted line
"-." Dash-dotted line Sample of dash-dotted line, with alternating dashes and dots
"none" No line No line

To display minor grid lines, use the grid minor command or set the XMinorGrid, YMinorGrid, or ZMinorGrid property to'on'.

Example: ax.MinorGridLineStyle = '-.'

Since R2023a

Minor grid line width, specified as a positive number. Set this property or the GridLineWidth property to control the thickness of the grid lines independently of the box outline and tick marks.

Tip

Since R2023a

How the minor grid line width is set, specified as one of these values:

MATLAB sets this property to "manual" when you explicitly set the MinorGridLineWidth property to a value.

Color of minor grid lines, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

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

Color Name Short Name RGB Triplet Hexadecimal Color Code Appearance
"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
"none" Not applicable Not applicable Not applicable No color

This table lists the default color palettes for plots in the light and dark themes.

Palette Palette Colors
"gem" — Light theme default_Before R2025a: Most plots use these colors by default._ Sample of the "gem" color palette
"glow" — Dark theme default Sample of the "glow" color palette

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem"); H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

To display minor grid lines, use the grid minor command or set the XMinorGrid, YMinorGrid, or ZMinorGrid property to'on'.

Example: ax.MinorGridColor = [0 0 1]

Example: ax.MinorGridColor = 'b'

Example: ax.MinorGridColor = 'blue'

Example: ax.MinorGridColor = '#0000FF'

Property for setting the minor grid color, specified as one of these values:

Labels

expand all

Text object for the axes title. To add a title, set the String property of the text object. To change the title appearance, such as the font style or color, set other properties. For a complete list, see Text Properties.

ax = gca; ax.Title.String = 'My Title'; ax.Title.FontWeight = 'normal';

Alternatively, use the title function to add a title and control the appearance.

title('My Title','FontWeight','normal')

Note

This text object is not contained in the axes Children property, cannot be returned by findobj, and does not use default values defined for text objects.

Text object for the axes subtitle. To add a subtitle, set the String property of the text object. To change its appearance, such as the font angle, set other properties. For a complete list, see Text Properties.

ax = gca; ax.Subtitle.String = 'An Insightful Subtitle'; ax.Subtitle.FontAngle = 'italic';

Alternatively, use the subtitle function to add a subtitle and control the appearance.

subtitle('An Insightful Subtitle','FontAngle','italic')

Or use the title function, and specify two character vector input arguments and two output arguments. Then set properties on the second text object returned by the function.

[t,s] = title('Clever Title','An Insightful Subtitle'); s.FontAngle = 'italic';

Note

This text object is not contained in the axes Children property, cannot be returned by findobj, and does not use default values defined for text objects.

Title and subtitle horizontal alignment with the plot box, specified as one of the values from the table.

TitleHorizontalAlignment Value Description Appearance
'center' The title and subtitle are centered over the plot box. Title and subtitle centered over the plot box.
'left' The title and subtitle are aligned with the left side of the plot box. Title and subtitle aligned with left edge of the plot box.
'right' The title and subtitle are aligned with the right side of the plot box. Title and subtitle aligned with right edge of the plot box.

Text object for axis label. To add an axis label, set theString property of the text object. To change the label appearance, such as the font size, set other properties. For a complete list, see Text Properties.

ax = gca; ax.YLabel.String = 'My y-Axis Label'; ax.YLabel.FontSize = 12;

Alternatively, use the xlabel, ylabel, and zlabel functions to add an axis label and control the appearance.

ylabel('My y-Axis Label','FontSize',12)

Note

These text objects are not contained in the axesChildren property, cannot be returned byfindobj, and do not use default values defined for text objects.

This property is read-only.

Legend associated with the Axes object, specified as aLegend object. To add a legend to the axes, use thelegend function. Then, you can use this property to modify the legend. For a complete list of properties, see Legend Properties.

plot(rand(3)) legend({'Line 1','Line 2','Line 3'},'FontSize',12) ax = gca; ax.Legend.TextColor = 'red';

You also can use this property to determine if the axes has a legend.

ax = gca; lgd = ax.Legend if ~isempty(lgd) disp('Legend Exists') end

Multiple Plots

expand all

Since R2023a

How to cycle through the line styles when there are multiple lines in the axes, specified as one of the values from this table.

The examples in this table were created using the default colors in theColorOrder property and three line styles (["-","-o","--"]) in the LineStyleOrder property.

Value Description Example
"aftercolor" Cycle through the line styles of the LineStyleOrder after the colors of the ColorOrder. Six lines that use the "aftercolor" line style cycling method. Each line is a different color with the same line style.
"beforecolor" Cycle through the line styles of theLineStyleOrder before the colors of theColorOrder. Six lines that use the "beforecolor" line style cycling method. The first three lines use all three line styles with the first color. The last three lines repeat the line styles with the second color.
"withcolor" Cycle through the line styles of theLineStyleOrder with the colors of theColorOrder. Six lines that use the "withcolor" line style cycling method. The first three lines use all three line styles with the first three colors. The last three lines repeat the line styles with the next three colors.

This property is read-only.

SeriesIndex value for the next plot object added to the axes, returned as a whole number greater than or equal to 0. This property is useful when you want to track how the objects cycle through the colors and line styles. This property maintains a count of the objects in the axes that have a numericSeriesIndex property value. MATLAB uses it to assign a SeriesIndex value to each new object. The count starts at 1 when you create the axes, and it increases by 1 for each additional object. Thus, the count is typically n+1, where n is the number of objects in the axes.

If you manually change the ColorOrderIndex orLineStyleOrderIndex property on the axes, the value of theNextSeriesIndex property changes to 0. As a consequence, objects that have a SeriesIndex property no longer update automatically when you change the ColorOrder orLineStyleOrder properties on the axes.

Color and Transparency Maps

expand all

Color map, specified as an m-by-3 array of RGB (red, green, blue) triplets that define m individual colors.

Example: ax.Colormap = [1 0 1; 0 0 1; 1 1 0] sets the color map to three colors: magenta, blue, and yellow.

MATLAB accesses these colors by their row number.

Alternatively, use the colormap function to change the color map.

Scale for color mapping, specified as one of these values:

Color limits for objects in axes that use the colormap, specified as a two-element vector of the form [cmin cmax]. This property determines how data values map to the colors in the colormap where:

The Axes object interpolates data values between cmin and cmax across the colormap. Values outside this range use either the first or last color, whichever is closest.

Transparency map, specified as an array of finite alpha values that progress linearly from0 to 1. The size of the array can be_m_-by-1 or 1-by-m. MATLAB accesses alpha values by their index in the array. An alphamap can be any length.

Scale for transparency mapping, specified as one of these values:

Alpha limits, specified as a two-element vector of the form [amin amax]. This property affects theAlphaData values of graphics objects, such as surface, image, and patch objects. This property determines how theAlphaData values map to the figure alpha map, where:

The Axes object interpolates data values betweenamin and amax across the figure alpha map. Values outside this range use either the first or last alpha map value, whichever is closest.

The Alphamap property of the figure contains the alpha map. For more information, see thealpha function.

Box Styling

expand all

Background color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

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

Color Name Short Name RGB Triplet Hexadecimal Color Code Appearance
"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
"none" Not applicable Not applicable Not applicable No color

This table lists the default color palettes for plots in the light and dark themes.

Palette Palette Colors
"gem" — Light theme default_Before R2025a: Most plots use these colors by default._ Sample of the "gem" color palette
"glow" — Dark theme default Sample of the "glow" color palette

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem"); H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Example: ax.Color = [0 0 1];

Example: ax.Color = 'b';

Example: ax.Color = 'blue';

Example: ax.Color = '#0000FF';

Line width of axes outline, tick marks, and grid lines, specified as a positive numeric value in point units. One point equals 1/72 inch.

Example: ax.LineWidth = 1.5

Box outline, 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.

Value Description 2-D Result 3-D Result
'on' Display the box outline around the axes. For 3-D views, use the BoxStyle property to change extent of the outline.Example: ax.Box = 'on' 2-D axes with the box outline on. The axes appears as a closed rectangle. 3-D axes with the box outline on. The axes appears as a closed cube.
'off' Do not display the box outline around the axes.Example: ax.Box = 'off' 2-D axes with the box outline off. The axes appears as an L shape consisting of one horizontal x-axis intersecting with one vertical y-axis. 3-D axes with the box outline off. The x-y plane is an L shape consisting of one x-axis intersecting with one y-axis. The z-axis extends up from a corner of the x-y plane.

The XColor,YColor, and ZColor properties control the color of the outline.

Example: ax.Box = 'on'

Box outline style, specified as 'back' or'full'. This property affects only 3-D views.

Value Description Result
'back' Outline the back planes of the 3-D box. Example: ax.BoxStyle = 'back' 3-D axes with the box style set to 'back'.
'full' Outline the entire 3-D box. Example: ax.BoxStyle = 'full' 3-D axes with the box style set to 'full'.

Clipping of objects to the axes limits, specified as'on' or 'off', or as numeric or logical 1 (true) or0 (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.

The clipping behavior of an object within the Axes object depends on both the Clipping property of the Axes object and theClipping property of the individual object. The property value of the Axes object has these effects:

This table lists the results for different combinations ofClipping property values.

Clipping Property for Axes Object Clipping Property for Individual Object Result
'on' 'on' Individual object is clipped. Others might or might not be.
'on' 'off' Individual object is not clipped. Others might or might not be.
'off' 'on' All objects are unclipped.
'off' 'off' All objects are unclipped.

Clipping boundaries, specified as one of the values in this table. If a plot contains markers, then as long as the data point lies within the axes limits, MATLAB draws the entire marker.

The ClippingStyle property has no effect if theClipping property is set to'off'.

Value Descriptions Illustration of Boundary Region
'3dbox' Clip plotted objects to the six sides of the axes box defined by the axis limits.Thick lines might display outside the axes limits. 3-D axes containing a plotted surface with the clipping style set to '3dbox'. The surface clips at the boundaries of the plot box.
'rectangle' Clip plotted objects to a rectangular boundary enclosing the axes in any given view.Clip thick lines at the axes limits. 3-D axes containing a plotted surface with the clipping style set to 'rectangle'. The surface extends beyond the plot box boundaries, but it clips to the edges of a rectangle that encloses the plot box.

Background light color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name. The background light is a directionless light that shines uniformly on all objects in the axes. To add light, use the light function.

For a custom color, specify an RGB triplet or a hexadecimal color code.

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

Color Name Short Name RGB Triplet Hexadecimal Color Code Appearance
"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
"none" Not applicable Not applicable Not applicable No color

This table lists the default color palettes for plots in the light and dark themes.

Palette Palette Colors
"gem" — Light theme default_Before R2025a: Most plots use these colors by default._ Sample of the "gem" color palette
"glow" — Dark theme default Sample of the "glow" color palette

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem"); H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Example: ax.AmbientLightColor = [1 0 1]

Example: ax.AmbientLightColor = 'm'

Example: ax.AmbientLightColor = 'magenta'

Example: ax.AmbientLightColor = '#FF00FF'

Position

expand all

Inner size and location, specified as a four-element vector of the form[left bottom width height]. This property is equivalent to the Position property.

Note

This property is read-only.

Margins for the text labels, returned as a four-element vector of the form[left bottom right top]. By default, MATLAB measures the values in units normalized to the container. To change the units, set the Units property.

The elements define the distances between the bounds of thePosition property and the extent of the surrounding text. The Position values combined with theTightInset values define the tightest bounding box that encloses the axes and the surrounding text.

These figures show the areas defined by theOuterPosition values (blue), thePosition values (red), and thePosition expanded by theTightInset values (magenta).

2-D View of Axes 3-D View of Axes
2-D axes with a title and axis labels. The blue outer position rectangle encloses the plot box, title, axis labels, and all tick values with an extra margin of space. The red position rectangle encloses the plot box only. And the magenta tight inset rectangle is tightly cropped to include the plot box, title, axis labels, and tick values with minimal extra space. 3-D axes with a title and axis labels. The blue outer position rectangle encloses the plot box, title, axis labels, and all tick values with an extra margin of space. The red position rectangle encloses the plot box, and potentially some of the tick values depending on the orientation of the plot box. The magenta tight inset rectangle is tightly cropped to include the plot box, title, axis labels, and tick values with minimal extra space.

For more information, see Control Axes Layout.

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

Note

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

Relative length of data units along each axis, specified as a three-element vector of the form [dx dy dz]. This vector defines the relative x, y, and_z_ data scale factors. For example, specifying this property as [1 2 1] sets the length of one unit of data in the _x_-direction to be the same length as two units of data in the _y_-direction and one unit of data in the_z_-direction.

Alternatively, use the daspect function to change the data aspect ratio.

Example: ax.DataAspectRatio = [1 1 1]

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

Data aspect ratio mode, specified as one of these values:

Relative length of each axis, specified as a three-element vector of the form [px py pz] defining the relative_x_-axis, _y_-axis, and_z_-axis scale factors. The plot box is a box enclosing the axes data region as defined by the axis limits.

Alternatively, use the pbaspect function to change the plot box aspect ratio.

If you specify the axis limits, data aspect ratio, and plot box aspect ratio, then MATLAB ignores the plot box aspect ratio. It adheres to the axis limits and data aspect ratio.

Example: ax.PlotBoxAspectRatio = [1 0.75 0.75]

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

Selection mode for the PlotBoxAspectRatio property, specified as one of these values:

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

To position the axes within the grid of a tiled chart layout, set theTile and TileSpan properties on theTiledChartLayoutOptions 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 axes ax in the third tile of the grid.

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

ax.Layout.TileSpan = [2 3];

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

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

If the axes 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.

View

expand all

Azimuth and elevation of view, specified as a two-element vector of the form [azimuth elevation] defined in degree units. Alternatively, use the view function to set the view.

Note

Setting the azimuth and elevation angles might reset other camera-related properties. For best results, set the azimuth and elevation angles before setting other camera-related properties.

Example: ax.View = [45 45]

Type of projection onto a 2-D screen, specified as one of these values:

Camera location, or the viewpoint, specified as a three-element vector of the form [x y z]. This vector defines the axes coordinates of the camera location, which is the point from which you view the axes. The camera is oriented along the view axis, which is a straight line that connects the camera position and the camera target. For an illustration, see Camera Graphics Terminology.

If the Projection property is set to 'perspective', then as you change theCameraPosition setting, the amount of perspective also changes.

Alternatively, use the campos function to set the camera location.

Example: ax.CameraPosition = [0.5 0.5 9]

Data Types: single | double

Selection mode for the CameraPosition property, specified as one of these values:

Camera target point, specified as a three-element vector of the form[x y z]. This vector defines the axes coordinates of the point. The camera is oriented along the view axis, which is a straight line that connects the camera position and the camera target. For an illustration, see Camera Graphics Terminology.

Alternatively, use the camtarget function to set the camera target.

Example: ax.CameraTarget = [0.5 0.5 0.5]

Data Types: single | double

Selection mode for the CameraTarget property, specified as one of these values:

Vector defining upwards direction, specified as a three-element direction vector of the form [x y z]. For 2-D views, the default value is [0 1 0]. For 3-D views, the default value is[0 0 1]. For an illustration, see Camera Graphics Terminology.

Alternatively, use the camup function to set the upwards direction.

Example: ax.CameraUpVector = [sin(45) cos(45) 1]

Selection mode for the CameraUpVector property, specified as one of these values:

Field of view, specified as a scalar angle greater than 0 and less than or equal to 180. Changing the camera view angle affects the size of graphics objects displayed in the axes, but does not affect the degree of perspective distortion. The greater the angle, the larger the field of view and the smaller objects appear in the scene. For an illustration, see Camera Graphics Terminology.

Example: ax.CameraViewAngle = 15

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

Selection mode for the CameraViewAngle property, specified as one of these values:

Interactivity

expand all

Since R2025a

Options to customize interaction behavior, specified as aCartesianAxesInteractionOptions object. Use the properties of the CartesianAxesInteractionOptions object to customize the behavior of interactions with the axes. For a complete list of properties, see CartesianAxesInteractionOptions Properties.

The options set by the CartesianAxesInteractionOptions object apply to these interactions on the associated axes:

Example: ax.InteractionOptions.LimitsDimensions = "x" constrains all pan and zoom interactions to the_x_-dimension.

Interactions, specified as an array of interaction objects or an empty array. The interactions you specify are available within your chart through gestures. You do not have to select any axes toolbar buttons to use them. For example, a panInteraction object enables dragging to pan within a chart. For a list of interaction objects, see Control Chart Interactivity.

The default set of interactions depends on the type of chart you are displaying. You can replace the default set with a new set of interactions, but you cannot access or modify any of the interactions in the default set. For example, this code replaces the default set of interactions with thepanInteraction and zoomInteraction objects.

ax = gca; ax.Interactions = [panInteraction zoomInteraction];

To remove all interactions from the axes, set this property to an empty array. To temporarily disable the current set of interactions, call thedisableDefaultInteractivity function. You can reenable them by calling the enableDefaultInteractivity function.

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.

Note

When the Visible property is 'off', the axes object is invisible, but child objects such as lines remain visible.

This property is read-only.

Location of mouse pointer, returned as a 2-by-3 array. TheCurrentPoint property contains the (x,y,z) coordinates of the mouse pointer with respect to the axes. The returned array is of the form:

[xfront yfront zfront xback yback zback]

The two points indicate the location of the last mouse click. However, if the figure has a WindowButtonMotionFcn callback defined, then the points indicate the last location of the mouse pointer. The figure also has a CurrentPoint property.

The values of the current point when using perspective projection can be different from the same point in orthographic projection because the shape of the axes volume can be different.

Orthogonal Projection

When using orthogonal projection, the values depend on whether the click is within the axes or outside the axes.

Perspective Projection

Clicking outside of the Axes object in perspective projection returns the front point as the current camera position. Only the back point updates with the coordinates of a point that lies on a line extending from the camera position through the pointer and intersecting the camera target at that point.

Callbacks

Callback Execution Control

expand all

This property is read-only.

Parent/Child

expand all

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

Identifiers

expand all

This property is read-only.

Type of graphics object returned as 'axes'.

Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value to serve as an identifier for an object. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.

Version History

Introduced before R2006a

expand all

The default ColorOrder, XColor,YColor, and ZColor property values in the light theme have changed slightly. This table lists the changes.

Property R2024b Color R2025a Color
ColorOrder RGB TripletSample[0.0000 0.4470 0.7410] Sample of dark blue color (R2024b)[0.8500 0.3250 0.0980] Sample of dark orange color (R2024b)[0.9290 0.6940 0.1250] Sample of dark yellow color (R2024b)[0.4940 0.1840 0.5560] Sample of dark purple color (R2024b)[0.4660 0.6740 0.1880] Sample of medium green color (R2024b)[0.3010 0.7450 0.9330] Sample of light blue color (R2024b)[0.6350 0.0780 0.1840] Sample of dark red color (R2024b) RGB TripletSample[0.0660 0.4430 0.7450] Sample of dark blue color (R2025a)[0.8660 0.3290 0.0000] Sample of dark orange color (R2025a)[0.9290 0.6940 0.1250] Sample of dark yellow color (R2025a)[0.5210 0.0860 0.8190] Sample of dark purple color (R2025a)[0.2310 0.6660 0.1960] Sample of medium green color (R2025a)[0.1840 0.7450 0.9370] Sample of light blue color (R2025a)[0.8190 0.0150 0.5450] Sample of dark magenta color (R2025a)
XColor, YColor, andZColor [0.15 0.15 0.15] [0.1294 0.1294 0.1294]

The FontSmoothing property has no effect and will be removed in a future release. You can set or get the value of this property without warning, but all text is smooth regardless of the property value. This property removal was announced in R2022a.

Use the LineStyleCyclingMethod property to control how different lines are distinguished from one another in the axes.

Change the thickness of grid lines independently of the box outline and tick marks by setting the GridLineWidth andMinorGridLineWidth properties of the axes. Before R2023a, the LineWidth property of the axes was the only property for controlling the grid line width. However, that property controlled the grid lines, box outline, and tick marks together. Now you can control the thickness of the grid lines separately.

Now you can control the selection mode for tick label rotation by setting theXTickLabelRotationMode,YTickLabelRotationMode, orZTickLabelRotationMode property.

You can remove all the tick marks from the axes by setting theTickDir property to "none".

Control the axis limits for your plots by setting theXLimitMethod, YLimitMethod, orZLimitMethod on the axes.

You can control the alignment of a plot title by setting theTitleHorizontalAlignment property of the axes to"left", "right", or"center".

Add a subtitle to your plot by setting the Subtitle property or calling the subtitle function. To control the appearance of the subtitle, set the SubtitleFontWeight property.

Set the PositionConstraint property of anAxes object to control the space around the plot box when you add or modify decorations such as titles and axis labels.

Setting or getting ActivePositionProperty is not recommended. Use thePositionConstraint property instead.

There are no plans to remove ActivePositionProperty, but the property is no longer listed when you call the set, get, orproperties functions on the axes.

To update your code, make these changes:

Setting or getting UIContextMenu property is not recommended. Instead, use the ContextMenu property, which accepts the same type of input and behaves the same way as theUIContextMenu property.

There are no plans to remove the UIContextMenu property, but it is no longer listed when you call the set, get, orproperties functions on the Axes object.

Use the Layout property to position anAxes object within a tiled chart layout.

If you change the axes ColorOrder orLineStyleOrder properties after plotting into the axes, the colors and line styles in your plot update immediately. In R2019a and previous releases, the new colors and line styles affect only subsequent plots, not the existing plots.

To preserve the original behavior, set the axes ColorOrderIndex orLineStyleOrderIndex property to any value (such as its current value) before changing the ColorOrder orLineStyleOrder property.

There is a new indexing scheme that enables you to change the colors and line styles of existing plots by setting the ColorOrder orLineStyleOrder properties. MATLAB applies this indexing scheme to all objects that have aColorMode, FaceColorMode,MarkerFaceColorMode, or CDataMode. As a result, your code might produce plots that cycle though the colors and line styles differently than in previous releases.

In R2019a and earlier releases, MATLAB uses a different indexing scheme which does not allow you to change the colors of existing plots.

To preserve the way your plots cycle through colors and line styles, set the axesColorOrderIndex or LineStyleOrderIndex property to any value (such as its current value) before plotting into the axes.

You can create a customized set of chart interactions by setting theInteractions property of the axes. These interactions are built into the axes and are available without having to select any buttons in the axes toolbar. Some types of interactions are enabled by default, depending on the content of the axes.

Use the Toolbar property to add a toolbar to the top-right corner of the axes for quick access to data exploration tools.