Basic UIList Example

This script is the UIList subclass used to show material slots, with a bunch of additional commentaries.

Notice the name of the class, this naming convention is similar as the one for panels or menus.


UIList subclasses must be registered for blender to use them.

import bpy

class MATERIAL_UL_matslots_example(bpy.types.UIList):
    # The draw_item function is called for each item of the collection that is visible in the list.
    #   data is the RNA object containing the collection,
    #   item is the current drawn item of the collection,
    #   icon is the "computed" icon for the item (as an integer, because some objects like materials or textures
    #   have custom icons ID, which are not available as enum items).
    #   active_data is the RNA object containing the active property for the collection (i.e. integer pointing to the
    #   active item of the collection).
    #   active_propname is the name of the active property (use 'getattr(active_data, active_propname)').
    #   index is index of the current item in the collection.
    def draw_item(self, context, layout, data, item, icon, active_data, active_propname, index):
        ob = data
        slot = item
        ma = slot.material
        # draw_item must handle the three layout types... Usually 'DEFAULT' and 'COMPACT' can share the same code.
        if self.layout_type in {'DEFAULT', 'COMPACT'}:
            # You should always start your row layout by a label (icon + text), this will also make the row easily
            # selectable in the list!
            # We use icon_value of label, as our given icon is an integer value, not an enum ID.
            # Note "data" names should never be translated!
            layout.label(text=ma.name if ma else "", translate=False, icon_value=icon)
            # And now we can add other UI stuff...
            # Here, we add nodes info if this material uses (old!) shading nodes.
            if ma and not context.scene.render.use_shading_nodes:
                manode = ma.active_node_material
                if manode:
                    # The static method UILayout.icon returns the integer value of the icon ID "computed" for the given
                    # RNA object.
                    layout.label(text="Node %s" % manode.name, translate=False, icon_value=layout.icon(manode))
                elif ma.use_nodes:
                    layout.label(text="Node <none>", translate=False)
        # 'GRID' layout type should be as compact as possible (typically a single icon!).
        elif self.layout_type in {'GRID'}:
            layout.alignment = 'CENTER'
            layout.label(text="", icon_value=icon)

# And now we can use this list everywhere in Blender. Here is a small example panel.
class UIListPanelExample(bpy.types.Panel):
    """Creates a Panel in the Object properties window"""
    bl_label = "UIList Panel"
    bl_idname = "OBJECT_PT_ui_list_example"
    bl_space_type = 'PROPERTIES'
    bl_region_type = 'WINDOW'
    bl_context = "object"

    def draw(self, context):
        layout = self.layout

        obj = context.object

        # template_list now takes two new args.
        # The first one is the identifier of the registered UIList to use (if you want only the default list,
        # with no custom draw code, use "UI_UL_list").
        layout.template_list("MATERIAL_UL_matslots_example", "", obj, "material_slots", obj, "active_material_index")

        # The second one can usually be left as an empty string. It's an additional ID used to distinguish lists in case you
        # use the same list several times in a given area.
        layout.template_list("MATERIAL_UL_matslots_example", "compact", obj, "material_slots",
                             obj, "active_material_index", type='COMPACT')

def register():

def unregister():

if __name__ == "__main__":

base class — bpy_struct

subclasses — MESH_UL_uvmaps_vcols, MESH_UL_vgroups, MATERIAL_UL_matslots, NODE_UL_interface_sockets, RENDERLAYER_UL_renderlayers, SCENE_UL_keying_set_paths, PHYSICS_UL_dynapaint_surfaces, MASK_UL_layers, UI_UL_list, RENDERLAYER_UL_linesets, TEXTURE_UL_texslots, CLIP_UL_tracking_objects, MESH_UL_shape_keys

class bpy.types.UIList(bpy_struct)

UI list containing the elements of a collection


If this is set, the uilist gets a custom ID, otherwise it takes the name of the class used to define the uilist (for example, if the class name is “OBJECT_UL_vgroups”, and bl_idname is not set by the script, then bl_idname = “OBJECT_UL_vgroups”)

Type :string, default “”, (never None)
  • DEFAULT Default Layout, Use the default, multi-rows layout.
  • COMPACT Compact Layout, Use the compact, single-row layout.
  • GRID Grid Layout, Use the grid-based layout.
Type :enum in [‘DEFAULT’, ‘COMPACT’, ‘GRID’], default ‘DEFAULT’, (readonly)
draw_item(context, layout, data, item, icon, active_data, active_property, index=0)

Draw an item in the list (NOTE: when you define your own draw_item function, you may want to check given ‘item’ is of the right type...)

  • layout (UILayout, (never None)) – Layout to draw the item
  • data (AnyType) – Data from which to take Collection property
  • item (AnyType) – Item of the collection property
  • icon (int in [0, inf]) – Icon of the item in the collection
  • active_data (AnyType, (never None)) – Data from which to take property for the active element
  • active_property (string, (never None)) – Identifier of property in active_data, for the active element
  • index (int in [0, inf], (optional)) – Index of the item in the collection

Inherited Properties

Inherited Functions

Table Of Contents

Previous topic


Next topic