Code covered by the BSD License  

Download apps, toolboxes, and other File Exchange content using Add-On Explorer in MATLAB.

» Watch video

Highlights from
gridLegend - a multi column format for legends

4.2 | 25 ratings Rate this file 206 Downloads (last 30 days) File Size: 5.3 KB File ID: #29248 Version: 1.4
image thumbnail

gridLegend - a multi column format for legends


Adrian Cherry (view profile)

  • 1 file
  • 4.21739


02 Nov 2010 (Updated )

Plot a multicolumn format legend.

| Watch this File

File Information

On a plot with a lot of traces the standard legend will often scroll off the bottom or the side of the figure, this function is intended to overcome this by allowing the user to define a multi column format for the legend.
Usage :
legHdl = gridLegend(hdl,nCols,gKey,'parameter_name','parameter_value',...);
Inputs :
hdl - a vector of graphic handles of the plotted data
nCols - the number of columns in the legend. (defaults to 2 if not defined)
gKey - a cell array of strings to display which should match the number of graphic handles in hdl (optional)
'parameter_name','parameter_value' - any parameter name pairs applicable to the legend
Output :
legHdl - a vector of graphic handles for the legend generated.
 Notes :
By default the legend will be arranged vertically, ie the second legend trace is placed under the first trace, filling the first column before moving onto the next. If you use the 'Orientation','Horizontal' parameter pair then the traces will be arranged horizontally, so the second trace will be in the second
column and so on to the end of the row, then moving down to the next row.
The parameter name / value pairs are passed over to the legend function so you can set things like 'Fontsize',8 etc.

The parameter / name pair of location can be used to place the legend - available options are
'location','bestoutside' : for 2 column legend uses 'eastoutside', more than 2 it uses 'southoutside'
'location','north' : places the legend centrally at the top of the axes
'location','northoutside' : places the legend centrally at the top of the figure
'location','eastoutside' : places the legend on the right of the figure
'location','southoutside' : places the legend centrally at the bottom of the figure
'location','westoutside' : places the legend on the left of the figure

 By default this is set to 'bestoutside'

This will work on x-y plots, bar and errorbar charts.

With many traces it's sometimes difficult to work out which trace the legend is referring to. From the MATLAB file exchange I've used a function called 'clickableLegend' which allows you to switch the plotted data on and off by clicking on the Legend key. This function will use clickableLegend if it can find it in your MATLAB path, otherwise it will revert back to the standard legend function.

Examples :

This will plot a vertical legend with two columns

This will plot a horizontal legend, 8 traces per row, and fontsize set to 8 points.

This will plot a vertical legend on the left hand side with 2 columns with the box switched off.

Note with versions earlier than R1014b you have to fiddle with the XColor and YColor
otherwise we end up with black lines for the X and Y axis.
       gridLegend(hdl,2,gKey,'location','westoutside','Fontsize',8,'Box','off','XColor',[1 1 1],'YColor',[1 1 1])


Clickable Legend Interactive Highlighting Of Data In Figures and Columnlegend inspired this file.

This file inspired Axlegend.

MATLAB release MATLAB 8.4 (R2014b)
MATLAB Search Path
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (46)
30 May 2016 Jacob D

It would also be good, if, like the Matlab legend() function, object_h is returned too.

Comment only
30 May 2016 Jacob D

Units of the legend and axes objects should be set the same prior to measurements and changes in the current code. Otherwise, mismatched units will cause offsets to be miscalculated.
A fix:

%% Additional Code 1
[legend_h,object_h] = fLegend(hdl,varargin{:});
origLegUnits = get(legend_h, 'units');
set(legend_h, 'units','points');

%% Additional Code 2
origAxUnits = get(axHdl, 'units');
set(axHdl, 'units','points');

%% Additional Code 3 (at end of function)
% Reset units
set(legend_h, 'units',origLegUnits);
set(axHdl, 'units',origAxUnits);

Comment only
26 May 2016 Mahmoud Zeydabadinezhad


hLegend = gridLegend(H(1:4),2,LEGEND(1:4),'Location',LegendPos,'Box','off');

Using the above code gives me the below error on R2016R:

Warning: Ignoring extra legend entries.
> In legend>set_children_and_strings (line 643)
In legend>make_legend (line 328)
In legend (line 257)
In gridLegend (line 109)
In plot_DTI_motion_parc (line 99)
Undefined operator '<' for input arguments of type 'cell'.

Error in gridLegend (line 114)
if gd < 2,

Error in plot_DTI_motion_parc (line 99)
hLegend = gridLegend(H(1:4),LEGEND(1:4),'Location',LegendPos,'Box','off'); %% removing the outter box of the legend

LEGEND is a 1x4 cell which contains the legend labels in it.

Comment only
25 May 2016 Tobias Haase

Hey Adrian,
I have some troubles using your otherwise great function with Matlab 2015 and Matlab 2016.
The handover of Fontsize is not working anymore. Anytime I tried to change Fontsize (same with your DEMO file) the spaces between the different entries will change but the fontsize itself will not change at all. There is no error posted by Matlab software. However, the other specs as e.g. box on/off etc. will work perfectly.
Do you or another member here have any idea how it could work?? Thank you for your help!

Best regards

Comment only
16 May 2016 Marc L.

Works great!

However, it doesn't seem to work when adding the Latex Interpreter parameter (i.e. calling for example gridLegend(hdl,3,array_params,'Interpreter','Latex');)

Is there a solution to this problem?

Comment only
04 May 2016 Keah Ying Lim

Very convenient function. Thanks, Adrian!

04 May 2016 Keah Ying Lim  
05 Apr 2016 Alessandro Masullo


10 Mar 2016 SabrinaP

I really like this function, it works great. The only issue I have is that the box of the legend is not centered with the subplots/plots. Is there a way you can fix that easily? Also, when I save it (using print function), the legend box appears over the plot box, just a little bit on the end. The format I have set is 5 horizontal subplots and each has its own legend to the right side in 2 columns.

08 Feb 2016 Felix Burget

Hi Adrian,

i am using the gridLegend as follows


where "planner_legend_names" is a cell array of legend names. Everything works fine for locations other than 'southoutside'. For the 'southoutside' setting the legend box covers the X-axis label and when the number of columns is 5 (or more) the pdf truncates the box of the legend on the left and right side. Is it possible to manually shift the legend box further down in order to not cover the Xaxis label. For the issue related to the number of columns I am ok with rearranging the legends to less than 5.
Thanks in advance! Best,

Comment only
05 Feb 2016 Adrian Cherry

Adrian Cherry (view profile)

  • 1 file
  • 4.21739

Hi Felix,
Normally it works fine for me to pdf and I'm struggling to get a test case which does truncate the legend. What version of MATLAB are you using? and number of lines plotted and any particular options, particularly location, would be useful to replicate the problem.

Comment only
02 Feb 2016 Felix Burget

Hi Adrian,
is it possible to properly export the graphics afterwards, e.g. to pdf. I tried using


but the resulting pdf truncates the legend. Do I have to follow another way in order to export it as a vector graphics?

Thank you for your answer in advance!

20 Jan 2016 Christian

Hi Adrian, that works! Thanks for this. Makes my plots look much nicer!

Comment only
20 Jan 2016 Christian  
20 Jan 2016 Adrian Cherry

Adrian Cherry (view profile)

  • 1 file
  • 4.21739

Hi Christian, many thanks for the feedback and for spotting the problem with the north location, it is one I had missed. Version 1.4 corrects this, calculated from the axes position and height to keep it inside the axes for different column numbers. Please let me know if this works for you. Adrian

Comment only
20 Jan 2016 Christian

This is a very convenient function! However, I've noticed using R2015a is that location "north" does not sit in my axes, but rather the top bar of the axes bisects the legend. I alleviated it by changing the height parameter in the position to lower the position from AxPosOut(4) by double the new height of the legend. Thanks!

Comment only
14 Dec 2015 Adrian Cherry

Adrian Cherry (view profile)

  • 1 file
  • 4.21739

Latest version (1.3) should now work with subplots. The demo file has an example.

Comment only
03 Dec 2015 Adrian Cherry

Adrian Cherry (view profile)

  • 1 file
  • 4.21739

The latest version (3/12/2015) should now work with the new graphics engine i.e. R2014b or newer.

The legend function no longer uses an additional set of axes to create the legend hence the problem with the dataaspectratio. After a bit of fiddling I found a way to hack it using fontsizes. So I've managed to test it ok on R2014b, hopefully someone can let me know if it works ok on R2015a/b.

Comment only
12 Aug 2015 Matias Lopez Abukalil

It sounds like a great file. However, I had the same problem that Nicholas using MATLAB2015a.

Has anyone found a solution for this?

Comment only
20 Jul 2015 Simon Woodward

Good job!

I have a scatter plot and am putting the legend at SouthOutside. It seems when the number of series is not a multiple of the number of columns, the legend is positioned so that the left hand edge is cut off. Any way to fix this?


13 Mar 2015 Nicholas

It seems that the 'dataaspectratio' property of legends has been removed in recent releases of matlab

I'm using 2014b and can not find this property, your function errors on line 232: set(legend_h,'dataaspectratio',[width/gd gd/numpercolumn 1]);

Any thoughts or suggestions around this would be helpful

Comment only
18 Dec 2014 Shuqin

Shuqin (view profile)

Wonderful! I think you solved the problem that many paper writer need to face. Thanks!

06 Nov 2014 Mahdi Ebrahimian

Hi Adrian,
Thanks for the nice function.
I want to have a row legend (three columns one row) but when I put column number equal to three I get an error message.
"Can't work out what sort of legend we've got - sorry bailing out"

Any suggestions to fix this?

04 Aug 2014 Todd

Todd (view profile)

Very easy to use and helpful. Thanks.

25 Jul 2014 Benedikt F

Did not work for a figure containing both error bar and x-y plots

10 Jul 2014 James

James (view profile)

Works very well, except when the figure is saved as a fig file. When the saved file is opened, the legend has reverted to single column. Recommendations for how to fix this issue appreciated.

Comment only
21 Feb 2014 Amanda

Amanda (view profile)

Hi, I love this function! My one big issue is that I sometimes find it hard to define a handle for the plotted data. Especially for compound graphs like a bar chart with error bars.

I get error for too many output arguments.

I am new to matlab so I hope someone could help me out here. Thank you!

09 Jan 2014 laoya

laoya (view profile)

Great jobs, thanks!
I wish the function support 'Best' like the legend function of matlab.

10 Sep 2013 Edward Byers

Doesn't work perfectly for subplots but...
I managed to get it to work reasonably well (on 1 occasion with an Area subplot) by...:
1) - Open gridLegend .m file and comment/delete line 273.
2) - If you are getting errors about Scribelegend, delete lines 278-284
3) - Specify a location (I used 'location','southoutside' )

Basically the issue with subplots (from what I can see) is that gridLegend is trying to control the 'gca' which doesn't seem to exist in subplots.

03 May 2013 Nicky

Nicky (view profile)

gridLegend doesn't seem to work when the figure contains subplots (it messes up the sizes of the subplots).
Is there any fix for this?

Comment only
10 Apr 2013 Jim

Jim (view profile)

This is a nice improvement in capability over columnLegend. Unfortunately, despite turning off the ScribeLegendListeners properties, I find that when a figure is saved and later reopened, the legend reverts to single-column format. My code has two calls to saveas near the end, one to save the figure in .fig format, and one to save it as a .emf file. Both are afflicted with single-column disease.

Comment only
21 Mar 2013 Johnny

Johnny (view profile)

Is there any way to adjust the spacing between two columns? Thanks.

28 Feb 2013 Matthias Pospiech

The script fails for my patch plots completely:

Index exceeds matrix dimensions.

Error in gridLegend (line 206)
set(object_h(linenum), 'ydata', [height-position*sheight height-position*sheight]);

Error in testplot (line 204)
legHdl = gridLegend(hplot,2,ltext)

with hplot and ltext both of size 1x6

14 Jun 2011 J G

J G (view profile)

Hi there, will this work on scatter plots? Thanks!

Comment only
29 May 2011 Bob Sturm

Bob Sturm (view profile)

Well done!

10 May 2011 sarah

sarah (view profile)

Hi Adrian,
thanks for uploading!
Any chance this can work for graphs including both lines and bars?

So far an example below doesn't produce a nice legend.

y=[2 3]'*x.^.5;
p=plot(x,y); hold on
gridlegend([p;b],2, {'line1' 'line2' 'bar'});

04 May 2011 James Hickey  
19 Apr 2011 Ruben

Ruben (view profile)

great idea, but the legend placement seems to go haywire. (at least in my case, where location is northoutside, 3 legend entries, 2 columns). Also some of the text and lines overlap.

L1 = {'Flapping angle $\Phi$ ' ,'Elevation angle $\theta$ ',...
'Feathering angle $\alpha$ '};
LH = gridLegend(fh,2,L1,'location','northoutside');

16 Apr 2011 Will DeShazer

I have found a collision. I have personalized my 'DefaultFigurePosition' to increase the figure window when it launches. It looks like:scrz=get(0,'ScreenSize');
set(0,'DefaultFigurePosition',[newxpos newypos xscale*scrz(3) yscale*scrz(4)]);

With this preference active, gridLegend generates a legend in which the text gets bunched up. As an example of something that gets bunched up:

a=[40 40 40 40:-1:21; 50 50 50 50:-1:31; 60 60 60 60:-1:41];

b=[1 2 3 ones(1,ndim-3)*4; 2 3 4 ones(1,ndim-3)*5; 3 4 5 ones(1,ndim-3)*6];


for i=1:ndim
l{i}=sprintf('Label %02i',i);


Can this be resolved easily or am I going to have to live with not using 'DefaultFigurePosition' when I want to use gridLegend?


Comment only
08 Feb 2011 George

George (view profile)

Hi there,

Please ignore the previous rating.
This function is really useful.

The only problem that I have with it is height of the legend just stays the same size, and the color bans are proportioned.

Eg. I have 9x1 legend originally and I want a 3x3 legend after running it through the function. I want the legend to be a 3rd of the original height and 3 times the original width/length. I want the legend to be compact rather than having heaps of white space

07 Feb 2011 Adrian Cherry

Adrian Cherry (view profile)

  • 1 file
  • 4.21739

Hi Robin,

Sorry to hear that my routine has trouble with the long legend titles, I've had a quick look at it and I can see where the problem lies. It's possible to apply a quick fix it but then it messes up the short titles.

My first suggestion in the specific example you have posted is to just use the standard legend function in MATLAB, if you apply the 'orientation','horizontal' pair to legend then you'll get a one row, two column legend.

Obviously this won't help if you want a 2x2 legend with long titles. In this case for the minute you'll have to tweak the code.

At line 232

% resize the data aspect ratio to match the new shape.
set(legend_h,'dataaspectratio',[width/gd gd/numpercolumn 1]);

You'll need to tweak the aspect ratio, in your case factor the y-axis by 4.
% resize the data aspect ratio to match the new shape.
set(legend_h,'dataaspectratio',[width/gd 4*gd/numpercolumn 1]);

I'm still looking at improving the calculation so that it'll do it automatically but for the minute I hope this helps.


Comment only
14 Jan 2011 Robin Jens  
14 Jan 2011 Robin Jens

Hi Adrian

I have a problems with placing the labels in two columns when the strings are very long. As example:

y=[2 3]'*x.^2;
gridLegend(hdlY,2,{'This is the most expensive beer in the world' 'This is the most cheapest bear in the world'},'location','southoutside')

Comment only
11 Jan 2011 Matthias Pospiech

The legend gets complete messed up once I apply any property of the fonts

hLegend = gridLegend(hplot,5,{legendStr}, 'FontSize' , FontSize - 2);

here the strings are outside of the legend box all written on top of each other, and the markers are not visible.

If this would work, I would apply 5 stars!

04 Nov 2010 Riccardo

Vey useful. Thanks for sharing

02 Nov 2010 Celine Cluzel

Hi Adrian,
thanks for uploading this. Very nice combination of clickableLegend and columnlegend. Seems to work very nicely with 'plot' graphs.
I'm trying to use it for bar charts - some problems so far with color of bars changing when clicking on the legend. I will come back with a specific question once I've identified what is the problem - if any.
Thank you

13 Jan 2011 1.1

Updated to work with errorbar chart legends.

Also fixed an edge case where there is only one trace per column. It didn't like it if you had 5 traces and asked for 5 columns, it placed all the keys and labels in the first column.

03 Dec 2015 1.2

The function should now be compatible with the new graphics system, i.e. R2014b or newer. I have tried to ensure it is still backward compatible with the earlier versions.

14 Dec 2015 1.3

Should now work with subplots - demo updated to display this. Also corrected a problem of blank columns if a large number of columns requested and only a few lines per column.

20 Jan 2016 1.4

Corrected North positioning

Contact us