Learn more about MATLAB

legend - Graph legend for lines and patches

Syntax

legend legend('string1','string2',...) legend(h,'string1','string2',...) legend(M) legend(h,M) legend(M,'parameter_name','parameter_value',...) legend(h,M,'parameter_name','parameter_value',...) legend(axes_handle,...) legend('off'), legend(axes_handle,'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(...,'Location',location) legend(...,'Orientation','orientation') [legend_h,object_h,plot_h,text_strings] = legend(...) legend(li_object,string1,string2,string3) legend(li_objects,M) legend('v6',M,...) legend('v6',AX)

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 uses the specified strings to label the corresponding graphics object (line, barseries, etc.).

legend(M) adds a legend containing the rows of the matrix or cell array of strings M as labels. For matrices, this is the same as legend(M(1,:),M(2,:),...).

legend(h,M) associates each row of the matrix or cell array of strings M with the corresponding graphics object (patch or line) in the vector of handles h.

legend(M,'parameter_name','parameter_value',...) and legend(h,M,'parameter_name','parameter_value',...) allow parameter/value pairs to be set when creating a legend (you can also assign them with set or with the Property Editor or Property Inspector). M must be a cell array of names. Legends inherit the properties of axes, although not all of them are relevant to legend objects.

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 string of the form data1, data2, etc. Setting display names is useful when you are experimenting with legends and might forget how objects in a lineseries, for example, are ordered.

When you specify legend strings in a legend command, their respective DisplayNames are set to these strings. If you delete a legend and then create a new legend without specifying labels for it, the values of DisplayName are (re)used as label names. Naturally, the associated plot objects must have a DisplayName property for this to happen: all _series and _group plot objects have a DisplayName property; Handle Graphics primitives, such as line and patch, do not.

Legends for graphs that contain groups of objects such as lineseries, barseries, contourgroups, etc. created by high-level plotting commands such as plot, bar, contour, etc., by default display a single legend entry for the entire group, regardless of how many member objects it contains. However, you can customize such legends to show individual entries for all or selected member objects and assign a unique DisplayName to any of them. You control how groups appear in the legend by setting values for their Annotation and DisplayName properties with M-code. For information and examples about customizing legends in this manner, see Controlling Legends in the MATLAB Graphics documentation.

You can specify EdgeColor and TextColor as RGB triplets or as ColorSpecs. You cannot set these colors to 'none'. To hide the box surrounding a legend, set the Box property to 'off'. To allow the background to show through the legend box, set the legend's Color property to 'none', for example,

set(legend_handle, 'Box', 'off')
set(legend_handle, 'Color', 'none')

This is similar to the effect of the command legend boxoff, except that boxoff also hides the legend's border.

You can use a legend's handle to set text properties for all the strings in a legend at once with a cell array of strings, rather than looping through each of them. See the last line of the example below, which demonstrates setting a legend's Interpreter property. In that example, you could reset the String property of the legend as follows:

set(h,'String',{'cos(x)','sin(x)'})

See the documentation for Text Properties for additional details.

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. A legend is created if one did not exist previously. Legends created automatically are limited to depict only the first 20 lines in the plot; if you need more legend entries, you can manually create a legend for them all with legend('string1','string2',...) syntax.

legend('boxoff'), legend(axes_handle,'boxoff') removes the box from the legend in the current axes or the axes specified by axes_handle, and makes its background transparent.

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

You can also type the above six commands using the syntax

legend keyword

If the keyword is not recognized, it is used as legend text, creating a legend or replacing the current legend.

legend_handle = legend(...) returns the handle to the legend on the current axes, or [] if no legend exists.

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 for 2-D plots)
`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 (default for 3-D plots)
`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

If the legend text does not fit in the 1-by-4 position vector, the position vector is resized around the midpoint to fit the legend text given its font and size, making the legend taller or wider. The location string can be all lowercase and can be abbreviated by sentinel letter (e.g., N, NE, NEO, etc.). Using one of the ...Outside values for location ensures that the legend does 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

The first column of the following table shows the now-obsolete specifiers for legend locations that were in use prior to Version 7, along with a description of the locations and their current equivalent syntaxes:

Obsolete Specifier	Location in Axes	Current Specifier
`-1`	Outside axes on right side	`NorthEastOutside`
`0`	Inside axes	`Best`
`1`	Upper right corner of axes	`NorthEast`
`2`	Upper left corner of axes	`NorthWest`
`3`	Lower left corner of axes	`SouthWest`
`4`	Lower right corner of axes	`SouthEast`

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

Backward Compatibility

legend('v6',M,...), for a cell array of strings M, creates a legend compatible with MATLAB 6.5 from the strings in M and any additional inputs.

legend('v6',AX), for an axes handle AX, updates any Version 6 legends and returns the legend handle.

The following calls to legend are passed to the Version 6 legend mechanism to maintain backward compatibility:

legend('DeleteLegend')
legend('EditLegend',h)
legend('ShowLegendPlot',h)
legend('ResizeLegend')
legend('RestoreSize',hLegend)
legend('RecordSize',hPlot)

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

Relationship to Axes

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.

You can only display 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

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.

Alternatives

Add a legend to a selected axes on a graph with the Insert Legend tool on the figure toolbar, or use Insert —> Legend from the figure menu. Use the Property Editor to modify the position, font, and other properties of a legend. For details, see Using Plot Edit Mode in the MATLAB Graphics documentation.

Moving the Legend

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.