MATLAB Function Reference

colorbar - Colorbar showing color scale

GUI Alternatives

Add a colorbar to a plot with the colorbar tool on the figure toolbar, or use Insert —> Colorbar from the figure menu. Use the Property Editor to modify the position, font and other properties of a legend. . For details, see Working in Plot Edit Mode in the MATLAB^® Graphics documentation.

Syntax

colorbar colorbar('off') colorbar('hide') colorbar('delete') colorbar(...,'peer',axes_handle) colorbar(...,'location') colorbar(...,'PropertyName',propertyvalue) cbar_axes = colorbar(...) colorbar(cbar_handle, PropertyName',propertyvalue,...)

Description

The colorbar function displays the current colormap in the current figure and resizes the current axes to accommodate the colorbar.

colorbar adds a new vertical colorbar on the right side of the current axes. If a colorbar exists in that location, colorbar replaces it with a new one. If a colorbar exists at a nondefault location, it is retained along with the new colorbar.

colorbar('off'), colorbar('hide'), and colorbar('delete') delete all colorbars associated with the current axes.

colorbar(...,'peer',axes_handle) creates a colorbar associated with the axes axes_handle instead of the current axes.

colorbar(...,'location') adds a colorbar in the specified orientation with respect to the axes. If a colorbar exists at the location specified, it is replaced. Any colorbars not occupying the specified location are retained. Possible values for location are

`North`	Inside plot box near top
`South`	Inside bottom
`East`	Inside right
`West`	Inside left
`NorthOutside`	Outside plot box near top
`SouthOutside`	Outside bottom
`EastOutside`	Outside right
`WestOutside`	Outside left

Using one of the ...Outside values for location ensures that the colorbar does not overlap the plot, whereas overlaps can occur when you specify any of the other four values.

colorbar(...,'PropertyName',propertyvalue) specifies property names and values for the axes object used to create the colorbar. See axes properties for a description of the properties you can set. The location property applies only to colorbars and legends, not to axes.

cbar_axes = colorbar(...) returns a handle to a new colorbar object, which is a child of the current figure. If a colorbar exists, a new one is still created.

colorbar(cbar_handle, PropertyName',propertyvalue,...) sets properties for the existing colorbar having the handle cbar_handle. To obtain the handle to an existing colorbar, use the command

cbar_handle = findobj(figure_handle,'tag','Colorbar')

where figure_handle is the handle of the figure containing the colorbar you want to modify. If the figure contains more than one colorbar, cbar_handle is returned as a vector, and you must choose which of the handles to specify to colorbar.

Backward-Compatible Version

h = colorbar('v6',...) creates a colorbar compatible with MATLAB 6.5 and earlier. It returns the handles of patch objects instead of a colorbar object.

Note The v6 option enables MATLAB Version 7.x users to create FIG-files that previous versions can open. It is obsolete and will be removed in a future version of MATLAB.

See Plot Objects and Backward Compatibility for more information.

Remarks

You can use colorbar with 2-D and 3-D plots.

Examples

Example 1

Display a colorbar beside the axes and use descriptive text strings as y-tick labels. Note that labels will repeat cyclically when the number of y-ticks is greater than the number of labels, and not all labels will appear if there are fewer y-ticks than labels you have specified. Also note that when colorbars are horizontal, their ticks and labels are governed by the XTick property rather than the YTick property. For more information, see Labeling Colorbar Ticks.

surf(peaks(30))
colorbar('YTickLabel',...
    {'Freezing','Cold','Cool','Neutral',...
     'Warm','Hot','Burning','Nuclear'})

Example 2

Display a horizontal colorbar beneath the axes of a filled contour plot:

contourf(peaks(60))
colormap cool
colorbar('location','southoutside')