- Undocumented Matlab - https://undocumentedmatlab.com -

Images in Matlab uicontrols & labels

Posted By Yair Altman On October 17, 2012 | 29 Comments

A couple of weeks ago, a reader here [1] asked how to integrate images in Matlab labels. I see quite a few queries about this, so I wanted to take today’s opportunity to explain how this can be done, and how to avoid common pitfalls.
In fact, there are two main methods of displaying images in Matlab GUI – the documented method, and the undocumented one:

The documented method

Some Matlab uicontrols (buttons, radio and checkboxes) have the CData [2] property that can be used to load and display an image. For example:

imgData = imread('myImage.jpg');   % or: imread(URL)
hButton = uicontrol('CData',imgData, ...);

While label uicontrols (uicontrol(‘style’,’text’, …)) also have the CData property, it has no effect on these controls. Instead, we can create an invisible axes that displays the image using the image function.

The undocumented method

web-based images

I’ve already written extensively about Matlab’s built-in support for HTML [3] in many of its controls. The supported HTML subset includes the <img> tag, and can therefore display images. For example:

htmlStr = 'Logo: ';
hButton = uicontrol('Position',[10,10,120,70], 'String',htmlStr, 'Background','white');

uicontrol with HTML image
uicontrol with HTML image

local images

Note that the image src (filename) needs to be formatted in a URL-compliant format such as 'http://www.website.com/folder/image.gif' or 'file:/c:/folder/subfolder/img.png'. If we try to use a non-URL-format filename, the image will not be rendered, only a placeholder box:

uicontrol('Position',..., 'String','');  %bad
uicontrol('Style','list', ... 'String',{...,''});  %bad

Ill-specified HTML images in Matlab uicontrols Ill-specified HTML images in Matlab uicontrols
Ill-specified HTML images in Matlab uicontrols

Instead, we need to use correct URI syntax when specifying local images, which means using the 'file:/' protocol prefix and the '/' folder separator:

>> iconsFolder = fullfile(matlabroot,'/toolbox/matlab/icons/');
>> iconUrl = strrep(['file:/' iconsFolder 'matlabicon.gif'],'\','/');
>> str = ['']
str =

>> uicontrol('Position',..., 'String',str);
>> uicontrol('Style','list', ... str});

Correctly-specified HTML images in Matlab uicontrols Correctly-specified HTML images in Matlab uicontrols
Correctly-specified HTML images in Matlab uicontrols

A similar pitfall exists when trying to integrate images in GUI control tooltips. I already discussed this issue here [4].
You can use HTML to resize the images, using the <img> tag’s width, height attributes. However, beware that enlarging an image might introduce pixelization effects. I discussed image resizing here [5] – that article was in the context of menu-item icons, but the discussion of image resizing also applies in this case.

images in text labels

As for text labels, since text-style uicontrols do not unfortunately support HTML, we can use the equivalent Java JLabels, as I have explained here [6]. Here too, we need to use the 'file:/' protocol prefix and the '/' folder separator if we want to use local files rather than internet files (http://…).

Java customizations

Using a uicontrol’s underlying Java component [7], we can customize the displayed image icon even further. For example, we can specify a different icon for selected/unselected/disabled/hovered/pressed/normal button states, as I have explained here [8]. In fact, we can even specify a unique icon that will be used for the mouse cursor when it hovers on the control:

Custom cursor Custom cursor
Custom uicontrol cursors

R2019b and newer

Iin R2019b and later, unless you specify the image size nothing will be shown. A solution is presented in this answer [9]

str = [''];

Categories: GUI, Icons, Low risk of breaking in future versions, Stock Matlab function, Undocumented feature

29 Comments (Open | Close)

29 Comments To "Images in Matlab uicontrols & labels"

#1 Comment By Morteza On October 17, 2012 @ 12:36

Hi Dear Yair
That was nice point…
Thanks so much for your help.

#2 Comment By Peter Gardman On October 20, 2012 @ 02:24

Dear Yair,
First, sorry, my petition is not related to this entry, but I didn’t know where to post it.
I use error(‘…’) when I want to stop execution of a running m-file and show an error message. However, together with the error message, Matlab displays on screen all the other info with the line number or the mfile name where the error occurred (“Error in ==>..”). This distracts from the error message, and the end-user doesn’t care about all this info. I only want to display a message and stop execution. For example:

if x < 0
   error('x should not be negative')

with pcoded files the extra info is not shown, but, in a non-compiled mfile, how to make "error(...)" not display all the extra info? Any suggestions are very welcome. Thank you very much.

#3 Comment By Yair Altman On October 20, 2012 @ 12:53

@Peter – place a try-catch block in the main function of your application:

function myApp(...)
      ... % main program code

#4 Comment By Peter Gardman On October 21, 2012 @ 02:36

Thank you very much for your answer. Very appreciated.

#5 Comment By stetsc On March 18, 2013 @ 05:27

Hi there Yair,

thanks for this very usefull post. But I have an ongoing question for this topic:

Is it possible to align text and image vertically centered?

Because in my Buttons, the text is aligned strictly at the bottom of the image. It would look more “professional” when I could align the text centered to the image.

#6 Comment By Yair Altman On March 18, 2013 @ 06:03

@Stetsc – yes, we can do this using the [16]:

jButton = findjobj(hButton);
jButton.setHorizontalTextPosition(javax.swing.SwingConstants.CENTER);  % or: set(jButton,'HorizontalTextPosition',javax.swing.SwingConstants.CENTER);
jButton.setVerticalTextPosition(javax.swing.SwingConstants.CENTER);    % or: set(jButton,'VerticalTextPosition',javax.swing.SwingConstants.CENTER);

This way, we can separately set the text and image locations in many different manners (left/center/right, top/center/bottom). I explain all these options in detail in section 6.1 of my Matlab-Java programming book.

#7 Comment By stetsc On March 18, 2013 @ 07:32

Hi Yair,

thanks for the quick answer. I tried out, what you told me, but I can’t see any changes in the alignment of the text and image on the Button.

Here is my code:

htmlButtonStr_aSi = ['Beschreibung der gewählten Messgröße: '];
DH.info_aSi = uicontrol(DH.var,'Style','PushButton',...       
                 'Units','normalized', ...
                 'FontUnits','normalized', ...    
                 'HorizontalAlignment','left', ...
                 'Enable','on', ...
                 'Callback','msgbox(char(DH.desc((get(DH.aSi,''Value'')))),''Info enthaltene Messgröße'')');
jButton_info_aSi = findjobj(DH.info_aSi);    %find Java-Handle of Button

I’m using MATLAB R2009b. Where is my fault?

#8 Comment By Yair Altman On March 18, 2013 @ 07:46




Also, to use HTML formatting as you are obviously trying to do, you need to add “<html>” to the beginning of your string:

htmlButtonStr_aSi = ['Beschreibung der gewählten Messgröße: '];

#9 Comment By stetsc On March 18, 2013 @ 08:07

Oh, I just saw, that your comment-system interprets the HTML-Tags in my first codeline. And with this, you cannot see what I really coded. So I try it this way:

htmlButtonStr_aSi = ['Beschreibung der gewählten Messgröße:;'];

As you can see, I build the string out of the descriptive string “Beschreibung der gewählten Messgröße:” and the variable “img_path_info”.

So why it does not work?

#10 Comment By stetsc On March 18, 2013 @ 08:11

I have to mention, that the Text and the image appear on the Button, side by side, as I want them to be, but the vertical positions are not really centered. The text is to low and the image to high.

Thanks for your help.

#11 Comment By Yair Altman On March 18, 2013 @ 08:15

HTML has its own way of aligning the items, just as on a webpage. If you want to have more control then you need to set the image not via HTML but using the uicontrol’s CData property, and then you can control the placement of them separately as I have shown above.

#12 Comment By stetsc On March 18, 2013 @ 08:35

Ah! I understand. Yair, you are my man!

Now it looks like I want it to. Many thanks for your help.

Here is the final code for all those who have the same problem out there:

info_icon_path = fullfile(pwd, '\resource\graph\info_icon_transparent.png');
DH.info_aSi = uicontrol(DH.var,'Style','PushButton',...       
                 'Units','normalized', ...
                 'FontUnits','normalized', ...    
                 'HorizontalAlignment','left', ...
                 'Enable','on', ...
                 'Callback','msgbox(''It works!'')');
jButton_info_nFS = findjobj(DH.info_nFS);                                           %find Java-Handle of Button
set(jButton_info_nFS,'HorizontalTextPosition',javax.swing.SwingConstants.RIGHT);    %align text
set(jButton_info_nFS,'VerticalTextPosition',javax.swing.SwingConstants.CENTER);     %align text

And now the button has the image on the left, followed by the descriptive text. Both are vertically centered.

So again, thanks to you, Yair.


#13 Comment By stetsc On March 18, 2013 @ 08:47

I forgot one codeline:

jButton_info_nFS.setIcon(javax.swing.ImageIcon(info_icon_path));    %add image to button

Just needs to be added to the previous posted code.
Sorry 🙂


#14 Comment By Yair Altman On March 18, 2013 @ 08:50

instead of using setIcon you could simply use the CData property:

imgData = imread(info_icon_path);
uicontrol(... , 'CData',imgData);

#15 Comment By Emanuel R On August 2, 2013 @ 05:45

How can I save the cdata as a gif? I want to use the Icons outside Matlab.

#16 Comment By Yair Altman On August 2, 2013 @ 06:19

@Emanuel – use the built-in imwrite function

#17 Comment By Asaf B On July 20, 2015 @ 10:28

Hi Yair,

is it possible to display HTML text on axes ?

%it is not work  
h_table = axes('HandleVisibility','callback', 'position',[ 0 0  1 1 ]);
htmlStr = 'Logo:';
h_DataText = text (0.5,0.5 ,htmlStr,'clipping','on','parent',h_table);

#18 Comment By Yair Altman On July 20, 2015 @ 10:53

@Asaf – Matlab axes only support tex/latex. For example, to get bold font using Tex,

text('Position',[0.5, 0.5], 'Interpreter','tex', 'String','\bfLogo');

Additional information: [17]

#19 Comment By Asaf B On July 21, 2015 @ 13:59

thank you 🙂

#20 Comment By Klaus On July 5, 2017 @ 11:44

Dear Yair,

thank you for the detailed description. Do you see a chance to put a 90 deg rotated text on a uicontrol (pushbutton)?

Best regars


#21 Comment By Yair Altman On July 6, 2017 @ 15:11

@Klaus – not directly, but you can create a small image and add it to the button’s CData. As long as you don’t resize the button too much in either direction, this should work nicely.

#22 Comment By Ronit On July 16, 2017 @ 10:39

Do you know a way to show images on push buttons via GUIDE?
Thanks in advance!

#23 Comment By Yair Altman On July 16, 2017 @ 19:27

@Ronit – you can update the button’s CData property. Read the Matlab documentation for the uicontrol function for details/examples.

#24 Comment By Sneha On July 21, 2017 @ 09:54

Hi Yair
I added image to my push button using the CData property but was not able to set its position.
The image added by me is positioned at the center of the button by default. Is there any way to change its position to bottom of the push button

#25 Comment By Yair Altman On July 21, 2017 @ 10:14

@Sneha – either enlarge your image by adding empty space at the top, or use Java by accessing the [18] and then calling [19].

#26 Comment By Sneha On July 21, 2017 @ 14:23

Hi Yair,
Tried enlarging my image and added empty space on top of the image and this worked. Thank you for the help. I wanted to align my text and tried using the following lines

jButton = findobj(hObject);
but got an error stating:
No appropriate method, property, or field 'setVerticalAlignment' for class 'matlab.ui.control.UIControl'.

Error in MSCT>pushbutton2_CreateFcn (line 812)

Error in gui_mainfcn (line 95)

Error in MSCT (line 44)
    gui_mainfcn(gui_State, varargin{:});

Error in

Can you please help me with this.

#27 Comment By Yair Altman On July 21, 2017 @ 14:27

You need to use findjobj, not findobj. Read the post (and the other articles on this blog) carefully.

#28 Comment By Sneha On July 21, 2017 @ 14:30

Hi, I am using MATLAB 2016 version

#29 Comment By Iliya Romm On February 9, 2020 @ 12:03

To anybody attempting this in R2019b (and later?): unless you specify the image size, nothing will be shown!. A solution is presented in [9]

str = [''];

Article printed from Undocumented Matlab: https://undocumentedmatlab.com

URL to article: https://undocumentedmatlab.com/articles/images-in-matlab-uicontrols-and-labels

URLs in this post:

[1] here: http://undocumentedmatlab.com/blog/html-support-in-matlab-uicomponents/#comment-110444

[2] CData: http://www.mathworks.co.uk/help/matlab/ref/uicontrol_props.html#bqxoijz

[3] built-in support for HTML: http://undocumentedmatlab.com/blog/html-support-in-matlab-uicomponents/

[4] here: http://undocumentedmatlab.com/blog/spicing-up-matlab-uicontrol-tooltips/

[5] here: http://undocumentedmatlab.com/blog/customizing-menu-items-part-3/#custom

[6] here: http://undocumentedmatlab.com/blog/customizing-matlab-labels/

[7] underlying Java component: http://undocumentedmatlab.com/blog/findjobj-find-underlying-java-object/

[8] here: http://undocumentedmatlab.com/blog/button-customization/

[9] this answer: https://www.mathworks.com/matlabcentral/answers/497260-figure-uitable-does-not-display-html-image-in-2019b#answer_411812

[10] Icon images & text in Matlab uicontrols : https://undocumentedmatlab.com/articles/icon-images-in-matlab-uicontrols

[11] Transparency in uicontrols : https://undocumentedmatlab.com/articles/transparency-in-uicontrols

[12] Customizing Matlab labels : https://undocumentedmatlab.com/articles/customizing-matlab-labels

[13] Panel-level uicontrols : https://undocumentedmatlab.com/articles/panel-level-uicontrols

[14] Uitab colors, icons and images : https://undocumentedmatlab.com/articles/uitab-colors-icons-images

[15] Toolbar button labels : https://undocumentedmatlab.com/articles/toolbar-button-labels

[16] : https://undocumentedmatlab.com/blog/findjobj-find-underlying-java-object/

[17] : http://www.mathworks.com/help/matlab/ref/text-properties.html

[18] : https://undocumentedmatlab.com/blog/button-customization

[19] : https://docs.oracle.com/javase/7/docs/api/javax/swing/AbstractButton.html#setVerticalAlignment(int)

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.