Accelerating the pace of engineering and science

# colorbar

Colorbar showing color scale

colorbar('peer',ax,__) is not recommended. Use colorbar(ax,__) instead.

## Syntax

• colorbar(ax,___)
• colorbar('peer',ax___)
• h = colorbar(___) example
• colorbar('off') example
• colorbar(h,'off')
• colorbar(ax,'off')

## Description

example

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

example

colorbar(placement) displays a colorbar in the location specified by placement, which is a location string such as 'northoutside'.

example

colorbar(Name,Value) specifies colorbar properties using one or more Name,Value pair arguments. For example, 'Direction','reverse' reveres the color scale.

colorbar(placement,Name,Value) specifies both the colorbar location and other colorbar properties.

colorbar(ax,___) adds a colorbar to the axes specified by ax instead of the current axes (gca). The option, ax, can precede any of the input argument combinations in the previous syntaxes.

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

example

h = colorbar(___) returns the colorbar object. Use h to set properties of the colorbar after it is created.

 Note:   Starting in R2014b, the colorbar function returns a colorbar object. In previous releases it returns an axes object.

example

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

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

colorbar(ax,'off') deletes all colorbars associated with the axes specified by ax instead of the current axes (gca).

## Examples

expand 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 Horizontal Colorbar to Graph

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

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

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


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


### 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)
h = colorbar;
h.Label.String = 'Elevation (ft in 1000s)';


### Delete Colorbar

Add a colorbar to a surface plot.

figure
surf(peaks)
colorbar


Delete the colorbar from the surface plot.

colorbar('off')


## Input Arguments

expand all

### placement — Colorbar location and orientation'eastoutside' (default) | location string

Colorbar location and orientation with respect to the axes, specified as a location string. This table lists the location strings.

StringResulting 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'). If you use the shorthand syntax, colorbar('northoutside'), then MATLAB® sets the colorbar Location property value to 'northoutside'.

Example: colorbar('westoutside')

### ax — Axes objectaxes object

Axes object. If you do not specify an axes, then the colorbar function adds a colorbar for the current axes.

### Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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

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

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

### 'Label' — Text to display along colorbartext object (default)

Text to display along the colorbar, specified as a text object. By default, there is no text along the colorbar. To add text, set the String property for the text object to the desired label. You can change the label appearance by setting other text properties. For a list, see Text Properties.

#### Example

This code creates a colorbar, returns the colorbar object as c, and adds a label.

c = colorbar;
c.Label.String = 'Label Text Goes Here';


This code changes the font size of the label.

c.Label.FontSize = 12;

### 'TickLabels' — Tick mark labelscell array of strings | numeric array | string

Tick mark labels, specified as a cell array of strings, a numeric array, 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'}

### 'TickLabelInterpreter' — Interpretation of characters in tick labels'tex' (default) | 'latex' | 'none'

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

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

• 'latex' — Interpret strings 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 text string.

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

ModifierDescriptionExample of String
^{ }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 when the interpreter is 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

Δ

\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

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

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

### 'Ticks' — Tick mark locationsvector 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. This is the default value.

• '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 size9 (default) | scalar value greater than zero

Font size, specified as a scalar value greater than zero in point units. The default value is 9 points. If you change the axes font size, then MATLAB automatically sets the colorbar font size to 90% of the axes font size. If you manually set the colorbar font size, then changing the axes font size does not affect the colorbar.

Example: 12

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

## Output Arguments

expand all

### h — Colorbar objectcolorbar object

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

expand all

### Tips

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