File Exchange

image thumbnail

gridLegend - a multi column format for legends

version (5.3 KB) by Adrian Cherry
Plot a multicolumn format legend.


Updated 20 Jan 2016

View Version History

View License

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])

Cite As

Adrian Cherry (2021). gridLegend - a multi column format for legends (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (60)


Hamdullah Livaoglu

it does not wotk on Handle inputs of type Figure ?

Hamdullah Livaoglu


Great function, I like it.
One issue I encountered is the following: when using copyobj() to copy the legend, it malforms. The copied object has only one column instead of multiple ones. Anyone encountered this?

Bob photonics

Running into two issues it won't allow to use the latex interpreter.
gKey={'HF$_2^-$/HF \% ', 'HF$_2^-$/H$_2$F$_2$ \% ','HF$_2^-$/(HF+H$_2$F$_2$) \% ','BOEX','pH','Etch depth 30min'};

Warning: Error updating Legend.

String must have valid interpreter syntax:
HF$_2^-$/HF \
> In defaulterrorcallback (line 12)
In legend>find_legend_info (line 400)
In legend>setOutArgs (line 678)
In legend (line 265)
In gridLegend (line 109)
.............. (continues of course for the other values)

FURTHERMORE it also doesn't stick to the 4 columns but turns it into 3 when I have 6 legend entries, I specifically want 4 columns as I'm specifying

zd z

when I used "gridLegend" function for "fill" function ,it does not works.
how to solve it?


A really useful tool ! But the 'fontsize' option can only change the size of the legend box, while the font of legend text remain the same. Are there anybody who know how to fix the problem ?


It's a great tool. However, it is not compatible with R2017a. It seems that in the latest release of MATLAB, they removed the 'dataaspectratio' property of the Legend class. So an error occurs when the function calls to set this property in line 232.



Echoing Tobias Haase's comment below. Fontsize does not change the font of the legend text, but does change the size of the legend box.

Georg Söllinger

Great Function!
Could it be, that the gridLegend doesnot work with fill?

Daisy Wan

Thanks for this great function.
I experience a issue with bar chart.
After saving the resulted plot to svg, a white diagional dotted line appear on each legend item, looking as if the rectangle is formed by 2 triangle. Any insight on workaround would be appreciated. I am working with matlab 2015b.


Hsieh-Chi Chang

I have a question. The works in legend box exceed the boundary. How do I change the box size to fit words? Thank you.

Jacob D

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

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);


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.

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

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?

Keah Ying Lim

Very convenient function. Thanks, Adrian!

Keah Ying Lim

Alessandro Masullo



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.

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,

Adrian Cherry

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.

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!


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


Adrian Cherry

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


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!

Adrian Cherry

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

Adrian Cherry

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.

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?

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?



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


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

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?


Very easy to use and helpful. Thanks.

Benedikt F

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


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.


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!


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

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.


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?


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.


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

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


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

Bob Sturm

Well done!


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'});

James Hickey


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');

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?



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

Adrian Cherry

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.


Robin Jens

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')

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!


Vey useful. Thanks for sharing

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

MATLAB Release Compatibility
Created with R2014b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!