LibIconPicker is a high-performance icon selection library for World of Warcraft addons. It provides a clean, callback-based API that lets addons open an icon picker and receive the selected icon instantly — without managing UI state, layouts, or large icon lists themselves.

Designed from the ground up to be lightweight and efficient, LibIconPicker uses a hybrid scroll frame and lazy rendering so only visible icons are processed at any time. This keeps CPU usage low during scrolling and filtering, even with very large icon sets, and avoids unnecessary redraws or background work.

The UI is lazy-loaded and initialized only when needed, ensuring minimal memory usage and zero impact on addon startup time. No persistent data or saved variables are created by the library, keeping memory footprints small and predictable.

LibIconPicker is designed to load on-demand, supports multiple addons simultaneously, and avoids global side effects by following established WoW library conventions. The result is a fast, scalable, and memory-efficient icon picker that integrates cleanly into any addon without adding performance overhead or maintenance burden.

LibIconPicker is NOT SAFE TO EMBED due to global XML frame names in the addon xml files.

Usage

The following example loads LibIconPicker on demand (if not already loaded) before invoking its public API. See the use cases for complete integration patterns and how this library can be leveraged by consumer addons.

local LoadAddOn     = LoadAddOn or C_AddOns.LoadAddOn
local IsAddOnLoaded = IsAddOnLoaded or C_AddOns.IsAddOnLoaded
local addOnName     = 'LibIconPicker'
local loaded, msg   = IsAddOnLoaded(addOnName), nil
if not loaded then
    loaded, msg = LoadAddOn(addOnName)
    if not loaded then
        return print('Failed to load LibIconPicker, msg:', msg)
    end
end
LibIconPicker:Open(function(sel)
    print('Selected icon:', sel.icon)
end)

API Definition

Full Documentation is here:

https://github.com/kapresoft/wow-addon-LibIconPicker

The public interface definition is here with EmmyLua annotations

LibIconPicker/Core/Lib/Developer/Interface/LibIconPickerPublicInterface.lua

LibIconPicker_Options

--- @type LibIconPicker_Options
local opt = {
    showTextInput = true,
    -- @type LibIconPicker_TextInputOptions
    textInput = { label = 'Enter Name:', value = 'Uber Spell' },
    -- @type LibIconPicker_Anchor
    anchor = {
        point = 'TOPRIGHT',
        relativeTo = UIParent,
        relativePoint = 'TOPRIGHT',
        x = -50,
        y = -100
    },
}

Callback: LibIconPicker_CallbackFn

LibIconPicker_Selection

--- @param sel LibIconPicker_Selection
function callbackFn(sel)
    -- sel.icon           : The user selected icon
    -- sel.textInputValue : The user text input value
end

Usage Example

Show icon picker with textInput and anchor

--- @type LibIconPicker_Options
local opt = {
    showTextInput = true,
    anchor = {
        point = 'TOPRIGHT',
        relativeTo = UIParent,
        relativePoint = 'TOPRIGHT',
        x = -50,
        y = -100
    },
}
--- @param sel LibIconPicker_Selection
LibIconPicker:Open(function(sel)
    print('Selected icon:', sel.icon, ' user-input-text:', sel.textInputValue)
end, opt)

Close the Icon Picker

LibIconPicker:Close()

General Comments

Drop your commments/questions here.

https://github.com/kapresoft/wow-addon-LibIconPicker/discussions/categories/general

Donations

As a software engineer, I am passionate about this project and have dedicated a significant amount of time and effort to creating a high-quality product. If you enjoy using this World of Warcraft add-on, please consider supporting me through a donation via Paypal™ or the Bitcoin Address provided below. Your support is greatly appreciated. Thank you in advance for your generosity.

Paypal™ Donation
Bitcoin Donation