legend (MATLAB Functions)

Display a legend on graphs

Syntax

legend('string1','string2',...)
legend(h,'string1','string2',...)
legend(string_matrix)
legend(h,string_matrix)
legend(axes_handle,...)
legend('off')
legend('toggle'), legend(axes_handle,'toggle')
legend('hide'), legend(axes_handle,'hide')
legend('show'), legend(axes_handle,'show')
legend('boxoff'), legend(axes_handle,'boxoff')
legend('boxon'), legend(axes_handle,'boxon')
legend_handle = legend(...)
legend
legend(legend_handle,...)
legend(...,'Location',location)
legend(...,'Orientation',orientation)
[legend_h,object_h,plot_h,text_strings] = legend(...)
legend(li_object,string1,string2,string3)
legend(li_object,M)

Description

legend places a legend on various types of graphs (line plots, bar graphs, pie charts, etc.). For each line plotted, the legend shows a sample of the line type, marker symbol, and color beside the text label you specify. When plotting filled areas (patch or surface objects), the legend contains a sample of the face color next to the text label.

The font size and font name for the legend strings match the Axes FontSize and FontName properties.

legend('string1','string2',...) displays a legend in the current axes using the specified strings to label each set of data.

legend(h,'string1','string2',...) displays a legend on the plot containing the objects identified by the handles in the vector h and using the specified strings to label the corresponding graphics object (line, barseries, etc.).

legend(string_matrix) adds a legend containing the rows of the matrix string_matrix as labels. This is the same as legend(string_matrix(1,:),string_matrix(2,:),...).

legend(h,string_matrix) associates each row of the matrix string_matrix with the corresponding graphics object in the vector h.

legend(axes_handle,...) displays the legend for the axes specified by axes_handle.

legend('off'), legend(axes_handle,'off') removes the legend in the current axes or the axes specified by axes_handle.

legend('toggle'), legend(axes_handle,'toggle') toggles the legend on or off. If no legend exists for the current axes, one is created using default strings.

The default string for an object is the value of the object's DisplayName property, if you have defined a value for DisplayName (which you can do using the Property Editor or calling set). Otherwise, legend constructs a sting of the form data1, data2, etc.

legend('hide'), legend(axes_handle,'hide') makes the legend in the current axes or the axes specified by axes_handle invisible.

legend('show'), legend(axes_handle,'show') makes the legend in the current axes or the axes specified by axes_handle visible.

legend('boxoff'), legend(axes_handle,'boxoff') removes the box from the legend in the current axes or the axes specified by axes_handle.

legend('boxon'), legend(axes_handle,'boxon') adds a box to the legend in the current axes or the axes specified by axes_handle.

legend_handle = legend returns the handle to the legend on the current axes or empty if no legend exists.

legend with no arguments refreshes all the legends in the current figure.

legend(legend_handle) refreshes the specified legend.

legend(...,'Location',location) uses location to determine where to place the legend. location can be either a 1-by-4 position vector ([left bottom width height]) or one of the following strings.

Specifier
Location in Axes

North
inside plot box near top

South
inside bottom

East
inside right

West
inside left

NorthEast
inside top right (default)

NorthWest
inside top left

SouthEast
inside bottom right

SouthWest
inside bottom left

NorthOutside
outside plot box near top

SouthOutside
outside bottom

EastOutside
outside right

WestOutside
outside left

NorthEastOutside
outside top right

NorthWestOutside
outside top left

SouthEastOutside
outside bottom right

SouthWestOutside
outside bottom left

Best
least conflict with data in plot

BestOutside
least unused space outside plot

Specifier	Location in Axes
`North`	inside plot box near top
`South`	inside bottom
`East`	inside right
`West`	inside left
`NorthEast`	inside top right (default)
`NorthWest`	inside top left
`SouthEast`	inside bottom right
`SouthWest`	inside bottom left
`NorthOutside`	outside plot box near top
`SouthOutside`	outside bottom
`EastOutside`	outside right
`WestOutside`	outside left
`NorthEastOutside`	outside top right
`NorthWestOutside`	outside top left
`SouthEastOutside`	outside bottom right
`SouthWestOutside`	outside bottom left
`Best`	least conflict with data in plot
`BestOutside`	least unused space outside plot

The location string can be all lower case and can be abbreviated by sentinel letter (e.g., N, NE, NEO, etc.). Using one of the ...Outside values for location assure that the colorbar will not overlap the plot, whereas overlaps can occur when you specify any of the other cardinal values. The location property applies to colorbars and legends, but not to axes.

Obsolete Location Values

Obsolete Specifier
Location in Axes

-1
outside axes on right side

0
inside axes

1
upper right corner of axes

2
upper left corner of axes

3
lower left corner of axes

4
lower right corner of axes

Obsolete Specifier	Location in Axes
-1	outside axes on right side
`0`	inside axes
`1`	upper right corner of axes
`2`	upper left corner of axes
`3`	lower left corner of axes
`4`	lower right corner of axes

legend(...,'Orientation','orientation') creates a legend with the legend items arranged in the specified orientation. orientation can be vertical (the default) or horizontal.

[legend_h,object_h,plot_h,text_strings] = legend(...) returns

legend_h -- Handle of the legend axes
object_h -- Handles of the line, patch and text graphics objects used in the legend
plot_h -- Handles of the lines and other objects used in the plot
text_strings -- Cell array of the text strings used in the legend

These handles enable you to modify the properties of the respective objects.

legend(li_object,string1,string2,string3) creates a legend for legendinfo objects li_objects with strings string1, etc.

legend(li_object,M) creates a legend of legendinfo objects li_objects where M is a string matrix or cell array of strings corresponding to the legendinfo objects.

Remarks

legend associates strings with the objects in the axes in the same order that they are listed in the axes Children property. By default, the legend annotates the current axes.

MATLAB displays only one legend per axes. legend positions the legend based on a variety of factors, such as what objects the legend obscures.

The properties that legends do not share with axes are:

Location
Orientation
EdgeColor
TextColor
Interpreter
String

You can use a legend's handle to set text properties for all the strings in a legend at once, rather than looping through each of them. See the last line example below, which demonstrates setting a legend's Interpreter property See the documentation for Text Properties for additional details.

legend installs a figure ResizeFcn, if there is not already a user-defined ResizeFcn assigned to the figure. This ResizeFcn attempts to keep the legend the same size.

Moving the Legend

You can move the legend by pressing the left mouse button while the cursor is over the legend and dragging the legend to a new location. Double-clicking a label allows you to edit the label.

Examples

Add a legend to a graph showing a sine and cosine function:

x = -pi:pi/20:pi;
plot(x,cos(x),'-ro',x,sin(x),'-.b')
h = legend('cos_x','sin_x',2);
set(h,'Interpreter','none')

In this example, the plot command specifies a solid, red line ('-r') for the cosine function and a dash-dot, blue line ('-.b') for the sine function.

See Also

LineSpec, plot

Adding a Legend to a Graph for more information on using legends

Annotating Plots for related functions

le legendre