Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

colorbar

Colorbar showing color scale

Syntax

colorbar
colorbar(target)
colorbar('peer',target)
colorbar(___,lcn)
colorbar(___,Name,Value)
c = colorbar(___)
colorbar('off')
colorbar(target,'off')
colorbar(c,'off')

Description

example

colorbar displays a vertical colorbar to the right of the current axes or chart. Colorbars display the current colormap and indicate the mapping of data values into the colormap.

colorbar(target) adds a colorbar to the axes or chart specified by target.

colorbar('peer',target) adds a colorbar to the axes specified by target. This syntax is not recommended and might be removed in a future release. Use colorbar(target) instead.

example

colorbar(___,lcn) displays the colorbar in the location specified by lcn, such as 'northoutside'. Specify lcn as the last argument in any of the previous syntaxes. Not all types of charts support modifying the colorbar location.

example

colorbar(___,Name,Value) modifies the colorbar appearance using one or more name-value pair arguments. For example, 'Direction','reverse' reverses the color scale. Specify Name,Value as the last pair of arguments in any of the previous syntaxes. Not all types of charts support modifying the colorbar appearance.

example

c = colorbar(___) returns the Colorbar object. You can use this object to set properties after creating the colorbar. Specify the return argument c with any of the previous syntaxes.

example

colorbar('off') deletes colorbars associated with the current axes or chart.

colorbar(target,'off') deletes colorbars associated with the axes or chart specified by target.

colorbar(c,'off') deletes the colorbar specified by c.

Examples

collapse all

Add a colorbar to a surface plot indicating the color scale.

figure
surf(peaks)
colorbar

By default, the colorbar function adds a vertical colorbar to the right side of the graph.

Add a horizontal colorbar below a plot by specifying the colorbar location as 'southoutside'.

figure
contourf(peaks)
colorbar('southoutside')

Reverse the direction of values in a colorbar on a graph by setting the 'Direction' property of the colorbar to 'reverse'.

figure
surf(peaks)
colorbar('Direction','reverse')

The colorbar values ascend from top to bottom instead of ascending from bottom to top.

Display the colorbar tick marks and tick labels on the side of a colorbar facing the surface plot.

surf(peaks)
colorbar('AxisLocation','in')

Create a figure with two subplots. Add colorbars to both subplots.

figure
subplot(2,1,1) % upper subplot 
surf(peaks)
colorbar

subplot(2,1,2) % lower subplot
contourf(peaks)
colorbar

Add a colorbar to a plot and specify the colorbar tick marks and tick labels. Specify the same number of tick labels as tick marks. If you do not specify enough tick labels, then the colorbar function repeats the labels.

contourf(peaks)
colorbar('Ticks',[-5,-2,1,4,7],...
         'TickLabels',{'Cold','Cool','Neutral','Warm','Hot'})

Add a text label along a colorbar.

surf(peaks)
c = colorbar;
c.Label.String = 'Elevation (ft in 1000s)';

Add a colorbar to a surface plot.

figure
surf(peaks)
colorbar

Delete the colorbar from the surface plot.

colorbar('off')

Input Arguments

collapse all

Colorbar location and orientation with respect to the axes, specified as one of the values in this table.

ValueResulting LocationResulting Orientation
'north'Top of axesHorizontal
'south'Bottom of axesHorizontal
'east'Right side of axesVertical
'west'Left side of axesVertical
'northoutside'Top outside of axesHorizontal
'southoutside'Bottom outside of axesHorizontal
'eastoutside'Right outside of axes (default)Vertical
'westoutside'Left outside of axesVertical

If a colorbar already exists in the specified location, then an updated colorbar replaces the existing one. To ensure that the colorbar does not overlap the graph, specify a location with the suffix, outside.

You also can set the colorbar location using its Location property. For example, colorbar('Location','northoutside') is the same as colorbar('northoutside').

Example: colorbar('westoutside')

Target for the colorbar, specified as an Axes object, a PolarAxes object, or a graphics object that has a ColorbarVisible property. For example, you can add or remove a colorbar from a HeatmapChart object.

If you do not specify the target, then the colorbar command affects the current axes (the object returned by gca).

Note

Some charts do not support modifying the colorbar appearance, such as the location, or returning the Colorbar object as an output argument.

Name-Value Pair Arguments

Example: colorbar('FontSize',12,'Direction','reverse') sets the font size of the colorbar to 12 points and reverses the orientation of the colorbar.

The colorbar properties listed here are only a subset. For a complete list see Colorbar Properties.

collapse all

Location with respect to the axes, specified as one of the values listed in this table.

ValueResulting LocationResulting Orientation
'north'Top of axesHorizontal
'south'Bottom of axesHorizontal
'east'Right side of axesVertical
'west'Left side of axesVertical
'northoutside'Top outside of axesHorizontal
'southoutside'Bottom outside of axesHorizontal
'eastoutside'Right outside of axes (default)Vertical
'westoutside'Left outside of axesVertical
'manual'Determined by Position propertyVertical

To display the colorbar in a location that does not appear in the table, use the Position property to specify a custom location. If you set the Position property, then MATLAB® sets the Location property to 'manual'. The associated axes does not resize to accommodate the colorbar when the Location property is set to 'manual'.

Tick mark labels, specified as a cell array of character vectors, a string array, a numeric array, a character vector, or a string. By default, the colorbar labels the tick marks with numeric values. If you specify labels and do not specify enough labels for all the tick marks, then MATLAB cycles through the labels.

Example: {'cold','warm','hot'}

Interpretation of tick label characters, specified as one of these values:

  • 'tex' — Interpret labels using a subset of the TeX markup.

  • 'latex' — Interpret labels using a subset of LaTeX markup.

  • 'none' — Display literal characters

TeX Markup

By default, MATLAB supports a subset of TeX markup. Use TeX markup to add superscripts and subscripts, modify the text type and color, and include special characters in the labels.

This table lists the supported modifiers when the TickLabelInterpreter property is set to 'tex', which is the default value. Most modifiers remain in effect until the end of the text. Superscripts and subscripts modify only the next character or the text within the curly braces {}.

ModifierDescriptionExample
^{ }Superscript'text^{superscript}'
_{ }Subscript'text_{subscript}'
\bfBold font'\bf text'
\itItalic font'\it text'
\slOblique font (rarely available)'\sl text'
\rmNormal font'\rm text'
\fontname{specifier}Set specifier as the name of a font family to change the font style. You can use this in combination with other modifiers.'\fontname{Courier} text'
\fontsize{specifier}Set specifier as a scalar numeric value to change the font size.'\fontsize{15} text'
\color{specifier}Set specifer as one of these colors: red, green, yellow, magenta, blue, black, white, gray, darkGreen, orange, or lightBlue.'\color{magenta} text'
\color[rgb]{specifier}Set specifier as a three-element RGB triplet to change the font color.'\color[rgb]{0,0.5,0.5} text'

This table lists the supported special characters with the Interpreter property set to 'tex'.

Character SequenceSymbolCharacter SequenceSymbolCharacter SequenceSymbol

\alpha

α

\upsilon

υ

\sim

~

\angle

\phi

\leq

\ast

*

\chi

χ

\infty

\beta

β

\psi

ψ

\clubsuit

\gamma

γ

\omega

ω

\diamondsuit

\delta

δ

\Gamma

Γ

\heartsuit

\epsilon

ϵ

\Delta

Δ

\spadesuit

\zeta

ζ

\Theta

Θ

\leftrightarrow

\eta

η

\Lambda

Λ

\leftarrow

\theta

θ

\Xi

Ξ

\Leftarrow

\vartheta

ϑ

\Pi

Π

\uparrow

\iota

ι

\Sigma

Σ

\rightarrow

\kappa

κ

\Upsilon

ϒ

\Rightarrow

\lambda

λ

\Phi

Φ

\downarrow

\mu

µ

\Psi

Ψ

\circ

º

\nu

ν

\Omega

Ω

\pm

±

\xi

ξ

\forall

\geq

\pi

π

\exists

\propto

\rho

ρ

\ni

\partial

\sigma

σ

\cong

\bullet

\varsigma

ς

\approx

\div

÷

\tau

τ

\Re

\neq

\equiv

\oplus

\aleph

\Im

\cup

\wp

\otimes

\subseteq

\oslash

\cap

\in

\supseteq

\supset

\lceil

\subset

\int

\cdot

·

\o

ο

\rfloor

\neg

¬

\nabla

\lfloor

\times

x

\ldots

...

\perp

\surd

\prime

´

\wedge

\varpi

ϖ

\0

\rceil

\rangle

\mid

|

\vee

\langle

\copyright

©

LaTeX Markup

To use LaTeX markup, set the TickLabelInterpreter property to 'latex'. The displayed text uses the default LaTeX font style. The FontName, FontWeight, and FontAngle properties do not have an effect. To change the font style, use LaTeX markup within the text.

The maximum size of the text that you can use with the LaTeX interpreter is 1200 characters. For multiline text, the maximum size of the text reduces by about 10 characters per line.

For more information about the LaTeX system, see The LaTeX Project Web site at http://www.latex-project.org/.

Tick mark locations, specified as a vector of monotonically increasing numeric values. The values do not need to be equally spaced. If you do not want tick marks displayed, then set the property to the empty vector, [].

Example: [-1,0,1,2,3,4,5]

Data Types: single | double

Direction of color scale, specified as one of these values:

  • 'normal' — Display the colormap and labels ascending from bottom to top for a vertical colorbar, and ascending from left to right for a horizontal colorbar.

  • 'reverse' — Display the colormap and labels descending from bottom to top for a vertical colorbar, and descending from left to right for a horizontal colorbar.

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.

If you change the axes font size, then MATLAB automatically sets the font size of the colorbar object to 90% of the axes font size. If you manually set the colorbar object font size, then changing the axes font size does not affect the colorbar object.

Output Arguments

collapse all

Colorbar object. Use c to set properties of the colorbar after it is created.

More About

collapse all

Compatibility Considerations

Starting in R2014b, the colorbar function returns a Colorbar object. In previous releases it returns an Axes object.

Tips

  • To add a text description along the colorbar, access the underlying text object using the Label property of the colorbar.

    c.Label.String = 'My Colorbar Label';
    

    To change the label appearance, such as the font style or color, set other text properties. For a list of properties, see Text Properties. For example, this code changes the font size.

    c.Label.FontSize = 12;

  • Adding a colorbar might resize the axes to accommodate the colorbar.

  • If an axes does not exist, then the colorbar function creates a blank axes and displays a colorbar with the default colormap.

  • You can use colorbar('delete') or colorbar('hide') instead of colorbar('off') to delete all colorbars in the current axes. All of these commands are equivalent.

Introduced before R2006a

Was this topic helpful?