Custom Python Tooltips for Blender UI Buttons

Creating customized tooltips in Blender enhances studio pipeline development by providing artists with contextual documentation, status checks, and clear instructions directly within the viewport interface. This article explains how to assign both static and dynamic tooltips to custom operators and UI layout buttons using Blender’s Python API (bpy).

Method 1: Static Tooltips via bl_description

The most common way to define a tooltip for a custom button is to set the bl_description class variable within a bpy.types.Operator. When this operator is rendered as a button in a panel (bpy.types.Panel), hovering over the button displays this text.

import bpy

class PIPELINE_OT_publish_asset(bpy.types.Operator):
    """Publish the current asset to the pipeline repository."""
    bl_idname = "pipeline.publish_asset"
    bl_label = "Publish Asset"
    bl_description = "Exports the selected model and writes metadata to the pipeline database"

    def execute(self, context):
        self.report({'INFO'}, "Asset published successfully.")
        return {'FINISHED'}

class PIPELINE_PT_main_panel(bpy.types.Panel):
    bl_label = "Pipeline Tools"
    bl_idname = "PIPELINE_PT_main_panel"
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'
    bl_category = "Pipeline"

    def draw(self, context):
        layout = self.layout
        layout.operator("pipeline.publish_asset", text="Publish Asset")

def register():
    bpy.utils.register_class(PIPELINE_OT_publish_asset)
    bpy.utils.register_class(PIPELINE_PT_main_panel)

def unregister():
    bpy.utils.unregister_class(PIPELINE_PT_main_panel)
    bpy.utils.unregister_class(PIPELINE_OT_publish_asset)

if __name__ == "__main__":
    register()

Method 2: Dynamic Tooltips Using the description Class Method

When building pipeline interfaces, tooltips often need to change based on the active object, selection state, or project settings. Blender allows you to define a @classmethod description on the operator to evaluate and return custom strings at runtime.

import bpy

class PIPELINE_OT_validate_mesh(bpy.types.Operator):
    bl_idname = "pipeline.validate_mesh"
    bl_label = "Validate Selection"

    @classmethod
    def description(cls, context, properties):
        obj = context.active_object
        if not obj:
            return "No active object selected. Select a mesh to validate."
        if obj.type != 'MESH':
            return f"Selected object '{obj.name}' is a {obj.type}. Mesh required."
        
        poly_count = len(obj.data.polygons)
        return f"Validate '{obj.name}' ({poly_count} polygons) for export checks."

    def execute(self, context):
        self.report({'INFO'}, "Mesh validated.")
        return {'FINISHED'}

The arguments provided to description() are:

  • context: The current Blender context (e.g., context.active_object, context.scene).
  • properties: The operator’s internal properties, allowing you to tailor messages if the button passes arguments.

Method 3: Custom Tooltips on Properties (layout.prop)

If a button is drawn using layout.prop() to represent a custom property or operator property, the tooltip is determined by the description argument passed during property definition.

import bpy

class PipelineSceneSettings(bpy.types.PropertyGroup):
    export_lod: bpy.props.EnumProperty(
        name="LOD Level",
        description="Select the Level of Detail (LOD) target for the export build",
        items=[
            ('LOD0', "LOD 0", "Highest resolution asset"),
            ('LOD1', "LOD 1", "Medium resolution proxy"),
            ('LOD2', "LOD 2", "Lowest resolution bounding proxy")
        ],
        default='LOD0'
    )

    auto_bake: bpy.props.BoolProperty(
        name="Auto-Bake Textures",
        description="When enabled, runs the texture baking routine before saving the asset",
        default=True
    )

Each item inside an EnumProperty can also take a third string parameter representing a tooltip dedicated to that specific dropdown item.

Best Practices for Pipeline UI Tooltips

  1. State Requirements: Use the dynamic description method to explain why a button might be disabled (poll failure) or what condition is missing.
  2. Shortcuts and Output: Include information about target directories, active pipeline environments, or shortcut triggers.
  3. Consistency: Use standard formatting across all pipeline operators (e.g., standard action description followed by requirements).