Custom icons in Blender UI

Mostly often Blender add-on developers use icons from Blender built-in library to personalize UI buttons. However, absolutely any external images can be uploaded and used as icons in the UI.

We can use images as icons in the UI using the “previews” module from the bpy.utils package.

To upload an image, which we will set as an icon on the button later, first create a “preview” collection:

Here we created an ImagePreviewCollection into which we can now load any images using the load() method.

To load an image into the preview collection, in the parameters of the load() method, we need to set:

  • name – name, identifier through which we will refer to the uploaded image in the collection.
  • path – full path to the uploaded image.
  • path_type – the loaded content type. Can be: ‘IMAGE’, ‘MOVIE’, ‘BLEND’, ‘FONT’. For images, the ‘IMAGE’ value must be specified.

Now let’s define a class for the simple user panel in the 3D viewport area with single button:

In the draw() function, in the description of the operator that will be called when the button is clicked, we used the “icon_value” parameter. The value for this parameter is the icon identifier, we took it from the preview collection created earlier, referring to the desired element by the given name (icons[‘crown’]) and getting the “icon_id” value from it.

Next, register the panel class in the Blender Python API:

Now, if we execute the register() function, in the user panel in the 3D viewport area we will see a button with our custom icon.

We can use absolutely any image as icons this way.

If we need to load several images to be placed on different buttons, each image must be loaded into the collection by calling the load() method and specifying the path to the desired image.

When we unregister the add-on, the preview collection must be removed from the API.

0 0 votes
Article Rating
Notify of

8 Comment
Oldest Most Voted
Inline Feedbacks
View all comments
24 days ago

Hi, I’m getting an error in draw.
KeyError: ‘crown’

I use Blender 4.0

Last edited 24 days ago by artur
7 months ago

How can I adjust the width of the icon?

Vinicius Guerrero
Vinicius Guerrero
8 months ago

What if you need icons to use dynamic web url images as sources?

10 months ago

How would you distribute this icon with an add on?

10 months ago
Reply to  jdh

Just distribute them in the add-on folder.