legend

Update axes' legend text, turn on/off the legend of axes. Toggle the states if no argument is used.

Syntax

legend()

legend(option)

legend(str1, str2, ...)

legend(str-cell)

legend(h-vector, str-cell)

legend(..., property, value)

lh = legend(...)

Inputs

option
One of the following options:
  • 'on': show the legend
  • 'off': hide the legend
  • 'boxon': show the legend background box
  • 'boxoff': hdie the legend background box
Type: string
Dimension: scalar
str1, str2
Legend text. str1 is the text for the first curve, str2 is the text for the second curve, etc.
Type: string
Dimension: scalar
str-cell
Legend text in a cell array.
Type: cell
h-vector
Handles of the curves which show legends.
Type: vector
property, value
'location'
Specifies the location of the legend.
Valid values for 2D plots are:
  • 'north'
  • 'south'
  • 'east'
  • 'west'
  • 'northeast'
  • 'northwest'
  • 'southeast'
  • 'southwest'
  • 'northoutside'
  • 'southoutside'
  • 'eastoutside'
  • 'westoutside'
  • or a real vector, specifying the location of the legend in normalized coordinates.
Valid values for 3D plots are:
  • 'northeast'
  • 'northwest'
  • 'southeast'
  • 'southwest'
'bordercolor'
Specifies the border color of the legend using an RGB vector with 3 elements ([R G B]).
'borderwidth'
Specifies the border width of the legend with a scalar.
.
'fontangle'
Specifies the font angle of the legend.
Valid values are:
  • 'italic'
  • 'regular'
'fontweight'
Specifies the font weight of the legend.
Valid values are:
  • 'bold'
  • 'normal'
'fontname'
Specifies the font name of the legend.
Valid values are all those available in Compose Preferences, such as:
  • 'Arial'
  • 'Calibri'
  • 'Cambria'
  • 'Courier New'
  • 'Garamond'
  • 'Helvetica'
  • 'Times New Roman'
  • 'Verdana'
  • ...
'fontsize'
Specifies the fontsize of the legend with a scalar.
.
'visible'
Specifies the visibility of the legend.
Valid values are :
  • 'on'
  • 'off'
Type: string | vector

Outputs

lh
Handle of the legend.
Type: double
Dimension: scalar

Example

Simple legend example.
clf;
plot(rand(1, 10));
legend('on');
legend('legend text');
Figure 1. Legend Example 1


Add legends for selected curves.
clf;
hold on;
h1 = plot(rand(10,1),'--o');
h2 = plot(rand(10,1),'-s');
h3 = plot(rand(10,1),'r^');
legend([h2,h3],{'curve2','curve3'});
Figure 2. Legend Example 2
Set the location of the legend.
clf;
plot(rand(1, 10));
legend('location','westoutside');
Figure 3. Location string example


Set legend location coordinates.
clf;
plot(rand(1, 10));
legend('location',[0.2 0.1]);
Figure 4. Location coordinates example


Example retrieving the legend handle.

clf;
plot(rand(1, 10));
h = legend('location',[0.2 0.1]);
get(h)
ans = struct [
  bordercolor: [Matrix] 1 x 3
  163  163  163
  borderwidth: 1
  children: [Matrix] 1 x 0
  fontangle: regular
  fontname: Arial
  fontsize: 7
  fontweight: normal
  handle: 14.4673228
  location: [Matrix] 1 x 2
  0.20000  0.10000
  parent: 19.6851603
  tag: 
  type: 
  uicontextmenu: 0
  units: pixels
  visible: on
]
Example setting legend properties.
clf;
plot(rand(1, 10));
h = legend('location',[0.2 0.1]);
set(h,'fontangle','italic');
set(h,'fontname','Times New Roman');
set(h,'borderwidth',3);
set(h,'bordercolor',[0 0 150]);
Figure 5. Legend Properties