colorbar

Colorbar showing color scale

Syntax

colorbar

colorbar(location)

colorbar(___,Name,Value)

colorbar(target,___)

c = colorbar(___)

colorbar('off')

colorbar(target,'off')

Description

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(location) displays the colorbar in a specific location such as 'northoutside'. Not all types of charts support modifying the colorbar location.

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.

colorbar(target,___) adds a colorbar to the axes or chart specified by target. Specify the target axes or chart as the first argument in any of the previous syntaxes.

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.

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

colorbar(target,'off') deletes all colorbars associated with the target axes or chart. Alternatively, you can specify a ColorBar object as the target.

Examples

Add Colorbar to Graph

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

surf(peaks)
colorbar

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

Add Horizontal Colorbar to Graph

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

contourf(peaks)
colorbar('southoutside')

Reverse Colorbar Direction

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

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

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

Display Colorbar Ticks on Opposite Side

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

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

Add Colorbars to Tiled Chart Layout

Starting in R2019b, you can display a tiling of plots using the tiledlayout and nexttile functions. Call the tiledlayout function to create a 2-by-1 tiled chart layout. Call the nexttile function to create the axes. Then display a surface plot in each axes with a colorbar.

tiledlayout(2,1)

% Top plot
nexttile 
surf(peaks)
colorbar

% Bottom plot
nexttile
mesh(peaks)
colorbar

Display Shared Colorbar in Tiled Chart Layout

When you want to share a colorbar between two or more plots, you can display the colorbar in a separate tile of the layout.

Create filled contour plots of the peaks and membrane data sets in a tiled chart layout.

Z1 = peaks;
Z2 = membrane;
tiledlayout(2,1);
nexttile
contourf(Z1)
nexttile
contourf(Z2)

Add a colorbar, and move it to the east tile.

cb = colorbar;
cb.Layout.Tile = 'east';

Specify Colorbar Ticks and Tick Labels

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'})

Label Colorbar

Add a text label along a colorbar.

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

Delete Colorbar

Add a colorbar to a surface plot.

surf(peaks)
colorbar

Delete the colorbar from the surface plot.

colorbar('off')

Input Arguments

location — Location

'eastoutside' (default) | 'north' | 'south' | 'east' | 'west' | 'northoutside' | ...

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

Value	Resulting Location	Resulting Orientation
'north'	Top of axes	Horizontal
'south'	Bottom of axes	Horizontal
'east'	Right side of axes	Vertical
'west'	Left side of axes	Vertical
'northoutside'	Top outside of axes	Horizontal
'southoutside'	Bottom outside of axes	Horizontal
'eastoutside'	Right outside of axes (default)	Vertical
'westoutside'	Left outside of axes	Vertical
'layout'	A tile in a tiled chart layout. To move the colorbar to a different tile, set the Layout property of the colorbar.	Depends on the shape of the tile

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

Axes object | PolarAxes object | GeographicAxes object | graphics object

Target object that contains the associated data visualization, specified as an Axes object, a PolarAxes object, a GeographicAxes object, or a graphics object that has a ColorbarVisible property. For example, a HeatmapChart object has the ColorbarVisible property.

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

Location — Location with respect to the axes

'eastoutside' (default) | 'north' | 'south' | 'east' | 'west' | 'northoutside' | ...

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

Value	Resulting Location	Resulting Orientation
'north'	Top of axes	Horizontal
'south'	Bottom of axes	Horizontal
'east'	Right side of axes	Vertical
'west'	Left side of axes	Vertical
'northoutside'	Top outside of axes	Horizontal
'southoutside'	Bottom outside of axes	Horizontal
'eastoutside'	Right outside of axes (default)	Vertical
'westoutside'	Left outside of axes	Vertical
'manual'	Determined by Position property	Vertical
'layout'	A tile in a tiled chart layout. To move the colorbar to a different tile, set the Layout property of the colorbar.	Depends on the shape of the tile

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

TickLabels — Tick mark labels

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

Tick mark labels, specified as a cell array of character vectors, a string array, a numeric array, a character vector, or a categorical array. 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.

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

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

TickLabelInterpreter — Tick label interpreter

'tex' (default) | 'latex' | 'none'

Tick label interpreter, 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. When you specify the tick labels, use dollar signs around each element in the cell array.

• '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.

Modifiers remain in effect until the end of the text. Superscripts and subscripts are an exception because they modify only the next character or the characters within the curly braces. When you set the interpreter to 'tex', the supported modifiers are as follows.

Modifier	Description	Example
^{ }	Superscript	'text^{superscript}'
_{ }	Subscript	'text_{subscript}'
\bf	Bold font	'\bf text'
\it	Italic font	'\it text'
\sl	Oblique font (usually the same as italic font)	'\sl text'
\rm	Normal font	'\rm text'
\fontname{specifier}	Font name — Replace specifier with the name of a font family. You can use this in combination with other modifiers.	'\fontname{Courier} text'
\fontsize{specifier}	Font size —Replace specifier with a numeric scalar value in point units.	'\fontsize{15} text'
\color{specifier}	Font color — Replace specifier with one of these colors: red, green, yellow, magenta, blue, black, white, gray, darkGreen, orange, or lightBlue.	'\color{magenta} text'
\color[rgb]{specifier}	Custom font color — Replace specifier with a three-element RGB triplet.	'\color[rgb]{0,0.5,0.5} text'

This table lists the supported special characters for the 'tex' interpreter.

Character Sequence	Symbol	Character Sequence	Symbol	Character Sequence	Symbol
\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'. Use dollar symbols around the labels, for example, use '$\int_1^{20} x^2 dx$' for inline mode or '$$\int_1^{20} x^2 dx$$' for display mode.

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 examples that use TeX and LaTeX, see Greek Letters and Special Characters in Chart Text. For more information about the LaTeX system, see The LaTeX Project website at https://www.latex-project.org/.

Ticks — Tick mark locations

vector of monotonically increasing numeric values

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 — Direction of color scale

'normal' (default) | 'reverse'

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.

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.

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

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.

Compatibility Considerations

'peer' input is not recommended

Not recommended starting in R2014b

Starting in R2014b, colorbar('peer',target) is not recommended and might be removed in a future release. Use colorbar(target) instead.