Documentation

legend('show') creates a legend that includes items for all charts in the current axes. For the labels, the legend uses the text from the DisplayName properties of the charts. If the DisplayName property is empty, then the legend uses a label of the form 'dataN'. If there are no charts in the axes, then this command creates an empty legend. If a legend exists, then this command ensures that it is visible.

legend(label1,...,labelN) sets the legend labels. Specify the labels as a list of character vectors, such as legend('Jan','Feb','Mar').

legend(labels) sets the labels using a cell array of character vectors or a character matrix; for example, legend({'Jan','Feb','Mar'}).

legend(labels,Name,Value) sets legend properties using one or more name-value pair arguments. You must specify the labels using a cell array; for example, legend({'A','B'},'FontSize',12).

legend(obj,___) only includes items in the legend for the graphics objects listed in obj. Specify the graphics objects before specifying the labels.

legend(ax,___) uses the axes specified by ax instead of the current axes. Specify the axes as the first input argument.

legend(___,'Location',lcn) sets the legend location. For example, 'Location','northeast' creates the legend in the upper right corner of the axes. You can use this option after any of the input argument combinations in the previous syntax group.

legend(___,'Orientation',ornt), where ornt is 'horizontal', displays the legend items side-by-side. The default for ornt is 'vertical', which stacks the items vertically.

legend(boxOption), where boxOption is 'off', removes the legend background and outline. The default for boxOption is 'on', which displays the legend background and outline.

lgd = legend(___) returns the legend object. Use lgd to query and set properties of the legend after it is created. For a list of properties, see Legend Properties.

[lgd,icons,plots,txt] = legend(___) additionally returns the objects used to create the legend icons, the objects plotted in the graph, and an array of the label text.

Note: This syntax is not recommended. It creates a legend that does not support all graphics features. Instead, use the lgd = legend(__) syntax to return the legend object and set Legend Properties.

legend(visibilityOption) controls the visibility of the legend, where visibilityOption is 'hide' or 'toggle'.

legend('off') deletes the legend.

Examples

Add Legend to Current Axes

Plot two lines and add a legend to the current axes. Specify the legend labels as input arguments to the legend function.

x = -pi:pi/20:pi;
y1 = sin(x);
plot(x,y1)

hold on
y2 = cos(x);
plot(x,y2,'--')
hold off

legend('sin(x)','cos(x)')

Specify Legend Labels During Plotting Commands

Plot two lines. Specify the legend labels during the plotting commands by setting the DisplayName property to the desired text. Then, add a legend.

x = linspace(-3,3,25);
y1 = sin(x);
plot(x,y1,'DisplayName','sin(x)')

hold on
y2 = cos(x);
plot(x,y2,'--','DisplayName','cos(x)')

legend('show')

Add Legend to Specific Axes

Create a figure with two subplots and return the two axes objects, ax1 and ax2. Plot random data in each subplot. Add a legend to the upper subplot by specifying ax1 as the first input argument to legend.

y1 = rand(3);
ax1 = subplot(2,1,1);
plot(y1)

y2 = rand(5);
ax2 = subplot(2,1,2);
plot(y2)

legend(ax1,'Line 1','Line 2','Line 3')

Specify Charts to Include in Legend

Plot three lines and return the chart line objects created. Then, create a legend that includes only two of the lines by specifying the first input argument as a vector of the chart line objects to include.

x = linspace(0,3*pi);
y1 = sin(x);
p1 = plot(x,y1);

hold on
y2 = sin(x - pi/4);
p2 = plot(x,y2);

y3 = sin(x - pi/2);
p3 = plot(x,y3);
hold off

legend([p1 p3],'First','Third')

Specify Legend Location and Orientation

Plot two lines and add a legend. Control the location of the legend by setting the Location property. Control the orientation by setting the Orientation property.

x = -pi:pi/20:pi;
y1 = sin(x);
plot(x,y1)

hold on
y2 = cos(x);
plot(x,y2,'--')
hold off

legend('sin(x)','cos(x)','Location','northwest','Orientation','horizontal')

Add Title to Legend

Plot two lines and create a legend. Then, add a title to the legend.

x = -pi:pi/20:pi;
y1 = sin(x);
plot(x,y1)

hold on
y2 = cos(x);
plot(x,y2)
hold off

lgd = legend('sin(x)','cos(x)');
title(lgd,'My Legend Title')

Modify Legend Appearance

Plot a line chart and a stem chart. Add a legend to the axes and set properties of the legend using name-value pair arguments. When you specify name-value pair arguments, you must specify the labels using a cell array.

x = linspace(-3,3,25);
y1 = sin(x);
plot(x,y1)

hold on
y2 = cos(x);
stem(x,y2)
hold off

legend({'sin(x)','cos(x)'},'FontSize',12,'TextColor','blue')

Modify Existing Legend

Plot a line chart and a stem chart. Add a legend to the axes and assign the legend object to the variable lgd. Then, use lgd to modify properties of the legend after it is created.

x = linspace(-3,3,25);
y1 = sin(x);
plot(x,y1,'DisplayName','sin(x)')

hold on
y2 = cos(x);
stem(x,y2,'DisplayName','cos(x)')
hold off

lgd = legend('show');
lgd.FontSize = 12;
lgd.TextColor = 'blue';

Remove Legend Background

Create a stem chart and a line chart. Add a legend to the lower left corner of the axes. Then, remove the legend background and outline.

x = linspace(0,2*pi,50);
y1 = sin(x);
stem(x,y1,'DisplayName','sin(x)')

hold on
y2 = cos(x);
plot(x,y2,'DisplayName','cos(x)')
hold off

legend('Location','southwest')
legend('boxoff')

Delete Legend

Create a chart with a legend. Then, delete the legend.

plot(rand(3))
legend('line 1','line 2','line 3')

legend('off')

Related Examples

Input Arguments

`label1,...,labelN` — Label for each graphics object (as separate arguments)
character vectors

Label for each graphics object, specified as separate arguments of character vectors. To include special characters or Greek letters in the labels, use TeX markup. For a table of options, see the Interpreter property. To specify labels that are keywords, such as 'Location' or 'off', use a cell array of character vectors or a character array.

Example: legend('Sin Function','Cos Function')

Example: legend('\gamma','\sigma')

`labels` — Label for each graphics object (as an array)
cell array of character vectors | character array

Label for each graphics object, specified as a cell array of character vectors or a character array. To include special characters or Greek letters in the labels, use TeX markup. For a table of options, see the Interpreter property.

Example: legend({'Sin Function','Cos Function'})

Example: legend(['Sin Function';'Cos Function'])

Example: legend({'\gamma','\sigma'})

`obj` — Graphics object to include in legend
vector

Graphics object to include in the legend, specified as a vector.

`ax` — Target axes
axes object | polar axes object

Target axes, specified as an axes object or a polar axes object. If you do not specify the axes, then the legend function uses the current axes.

`lcn` — Legend location
`'north'` | `'south'` | `'east'` | `'west'` | `'northeast'` | ...

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

Value	Description
`'north'`	Inside top of axes
`'south'`	Inside bottom of axes
`'east'`	Inside right of axes
`'west'`	Inside left of axes
`'northeast'`	Inside top-right of axes (default for 2-D axes)
`'northwest'`	Inside top-left of axes
`'southeast'`	Inside bottom-right of axes
`'southwest'`	Inside bottom-left of axes
`'northoutside'`	Above the axes
`'southoutside'`	Below the axes
`'eastoutside'`	To the right of the axes
`'westoutside'`	To the left of the axes
`'northeastoutside'`	Outside top-right corner of the axes (default for 3-D axes)
`'northwestoutside'`	Outside top-left corner of the axes
`'southeastoutside'`	Outside bottom-right corner of the axes
`'southwestoutside'`	Outside bottom-left corner of the axes
`'best'`	Inside axes where least conflict occurs with plot data
`'bestoutside'`	To the right of the axes
`'none'`	Determined by `Position` property. Use the `Position` property to display the legend in a custom location.

Example: legend('Location','northeastoutside')

`ornt` — Orientation
`'vertical'` (default) | `'horizontal'`

Orientation, specified as one of these values:

'vertical' — Stack the legend items vertically.
'horizontal' — List the legend items side-by-side.

Example: legend('Orientation','horizontal')

`boxOption` — Display of legend background
`'boxon'` (default) | `'boxoff'`

Display of legend background, specified as one of these values:

'boxon' — Display the legend background and outline.
'boxoff' — Do not display the legend background and outline

Example: legend('boxoff')

`visibilityOption` — Legend visibility
`'hide'` | `'toggle'`

Legend visibility, specified as one of these values:

'hide' — Hide the legend.
'toggle' — Toggle the legend visibility.

Example: legend('toggle')

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: legend({'A','B'},'FontSize',12,'TextColor','blue') creates a legend with blue, 12-point font.

The properties listed here are only a subset. For a complete list, see Legend Properties.

`'TextColor'` — Text color
`[0 0 0]` (default) | RGB triplet | character vector of color name

Text color, specified as an RGB triplet or a character vector of a color name. The default color is black with an RGB triplet value of [0 0 0].

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. This table lists the long and short color name options and the equivalent RGB triplet values.

Long Name	Short Name	RGB Triplet
`'yellow'`	`'y'`	`[1 1 0]`
`'magenta'`	`'m'`	`[1 0 1]`
`'cyan'`	`'c'`	`[0 1 1]`
`'red'`	`'r'`	`[1 0 0]`
`'green'`	`'g'`	`[0 1 0]`
`'blue'`	`'b'`	`[0 0 1]`
`'white'`	`'w'`	`[1 1 1]`
`'black'`	`'k'`	`[0 0 0]`

Example: [0 0 0.5]

Example: 'blue'

`'FontSize'` — Font size
`9` (default) | scalar value greater than zero

Font size, specified as a scalar value greater than zero in point units. If you change the axes font size, then MATLAB^® automatically sets the legend font size to 90% of the axes font size. If you manually set the legend font size, then changing the axes font size does not affect the legend.

`'Interpreter'` — Interpretation of text characters
`'tex'` (default) | `'latex'` | `'none'`

Interpretation of text characters, specified as one of these values:

'tex' — Interpret characters using a subset of TeX markup.
'latex' — Interpret characters using 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 font type and color, and include special characters in the text.

This table lists the supported modifiers with the Interpreter property set to 'tex'. Modifiers remain in effect until the end of the text. Superscripts and subscripts are an exception because they only modify the next character or the characters within the curly braces.

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 — Set `specifier` as the name of a font family. You can use this in combination with other modifiers.	`'\fontname{Courier} text'`
`\fontsize{specifier}`	Font size — Set `specifier` as a numeric scalar value in point units to change the font size.	`'\fontsize{15} text'`
`\color{specifier}`	Font color — 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}`	Custom font color — Set `specifier` as a three-element RGB triplet.	`'\color[rgb]{0,0.5,0.5} text'`

This table lists the supported special characters with the Interpreter property set to 'tex'.

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 Interpreter property to 'latex'. Use dollar symbols around the text, 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.

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

For more information about the LaTeX system, see The LaTeX Project website at http://www.latex-project.org/.

Output Arguments

`lgd` — Legend object
legend object

Legend object. Use lgd to view or modify properties of the legend after it is created.

plot(rand(3))
lgd = legend('line1','line2','line3');
lgd.FontSize = 12;
lgd.FontWeight = 'bold';

Note: Starting in R2014b, the legend function returns a legend object. For earlier releases, it returns an axes object.

`icons` — Objects used to create legend icons and labels
text, patch, and line objects

Objects used to create the legend icons and labels, returned as text, patch, and line objects.

Note: This output argument is not recommended.

`plots` — Objects plotted in axes
vector of graphics objects

Objects plotted in the axes, returned as a vector of graphics objects.

Note: This output argument is not recommended.

`txt` — Text used for legend labels
cell array of character vectors

Text used for legend labels, returned as a cell array of character vectors.

Note: This output argument is not recommended. Instead, access the labels using the String property of the legend.

More About