Skip to main content

​
Combo Box Widgets

Combo boxes allow selecting one item from a dropdown list.

​
BeginCombo

bool ImGui::BeginCombo(const char* label, const char* preview_value, ImGuiComboFlags flags = 0)
Begin a combo box. The BeginCombo()/EndCombo() API allows you to manage your contents and selection state however you want it, by creating e.g. Selectable() items.
​
label
const char*
Combo box label
​
preview_value
const char*
Preview text displayed when combo is closed
​
flags
ImGuiComboFlags
default:"0"
Combo flags (see ImGuiComboFlags_)
​
return
bool
True when combo is open (you can output to it)
// Example
const char* items[] = { "Apple", "Banana", "Cherry" };
static int item_current = 0;

if (ImGui::BeginCombo("Fruits", items[item_current])) {
    for (int n = 0; n < IM_COUNTOF(items); n++) {
        bool is_selected = (item_current == n);
        if (ImGui::Selectable(items[n], is_selected)) {
            item_current = n;
        }
        if (is_selected) {
            ImGui::SetItemDefaultFocus();
        }
    }
    ImGui::EndCombo();
}

​
EndCombo

void ImGui::EndCombo()
End combo box. Only call EndCombo() if BeginCombo() returns true.

​
Combo (array)

bool ImGui::Combo(const char* label, int* current_item, const char* const items[], int items_count, int popup_max_height_in_items = -1)
Simple combo box helper over BeginCombo()/EndCombo().
​
label
const char*
Combo box label
​
current_item
int*
Pointer to current selected item index
​
items
const char* const[]
Array of item strings
​
items_count
int
Number of items in array
​
popup_max_height_in_items
int
default:"-1"
Maximum height of popup in items (-1 = default)
​
return
bool
True when selection has been modified
// Example
const char* items[] = { "Apple", "Banana", "Cherry", "Kiwi", "Mango" };
static int item_current = 0;
ImGui::Combo("Fruits", &item_current, items, IM_COUNTOF(items));

​
Combo (separated string)

bool ImGui::Combo(const char* label, int* current_item, const char* items_separated_by_zeros, int popup_max_height_in_items = -1)
Combo box with items separated by \0 within a string. End item-list with \0\0. E.g. "One\0Two\0Three\0"
​
label
const char*
Combo box label
​
current_item
int*
Pointer to current selected item index
​
items_separated_by_zeros
const char*
String with items separated by \0
​
popup_max_height_in_items
int
default:"-1"
Maximum height of popup in items
​
return
bool
True when selection has been modified
// Example
static int item_current = 0;
ImGui::Combo("Combo", &item_current, "Apple\0Banana\0Cherry\0");

​
Combo (callback)

bool ImGui::Combo(const char* label, int* current_item, const char* (*getter)(void* user_data, int idx), void* user_data, int items_count, int popup_max_height_in_items = -1)
Combo box with callback to get item strings.
​
label
const char*
Combo box label
​
current_item
int*
Pointer to current selected item index
​
getter
const char* (*)(void*, int)
Callback function to get item string by index
​
user_data
void*
User data passed to callback
​
items_count
int
Number of items
​
popup_max_height_in_items
int
default:"-1"
Maximum height of popup in items
​
return
bool
True when selection has been modified
// Example
struct MyData {
    const char* items[3] = { "One", "Two", "Three" };
};

static const char* MyItemGetter(void* data, int idx) {
    MyData* my_data = (MyData*)data;
    return my_data->items[idx];
}

MyData my_data;
static int item_current = 0;
ImGui::Combo("Combo", &item_current, MyItemGetter, &my_data, 3);

​
Combo Flags

​
ImGuiComboFlags_

Flags for BeginCombo().
FlagDescription
ImGuiComboFlags_NoneDefault
ImGuiComboFlags_PopupAlignLeftAlign the popup toward the left by default
ImGuiComboFlags_HeightSmallMax ~4 items visible
ImGuiComboFlags_HeightRegularMax ~8 items visible (default)
ImGuiComboFlags_HeightLargeMax ~20 items visible
ImGuiComboFlags_HeightLargestAs many fitting items as possible
ImGuiComboFlags_NoArrowButtonDisplay on the preview box without the square arrow button
ImGuiComboFlags_NoPreviewDisplay only a square arrow button
ImGuiComboFlags_WidthFitPreviewWidth dynamically calculated from preview contents
// Examples

// Left-aligned popup
if (ImGui::BeginCombo("##combo", "Preview", ImGuiComboFlags_PopupAlignLeft)) {
    ImGui::Selectable("Item 1");
    ImGui::Selectable("Item 2");
    ImGui::EndCombo();
}

// Small height
if (ImGui::BeginCombo("Small", "Preview", ImGuiComboFlags_HeightSmall)) {
    for (int i = 0; i < 10; i++) {
        char buf[32];
        sprintf(buf, "Item %d", i);
        ImGui::Selectable(buf);
    }
    ImGui::EndCombo();
}

// No arrow button
if (ImGui::BeginCombo("##combo2", "No Arrow", ImGuiComboFlags_NoArrowButton)) {
    ImGui::Selectable("Item 1");
    ImGui::EndCombo();
}

// No preview (only arrow)
if (ImGui::BeginCombo("##combo3", NULL, ImGuiComboFlags_NoPreview)) {
    ImGui::Selectable("Item 1");
    ImGui::EndCombo();
}

// Width fits preview
if (ImGui::BeginCombo("Auto Width", "This determines width", ImGuiComboFlags_WidthFitPreview)) {
    ImGui::Selectable("Item 1");
    ImGui::Selectable("Item 2");
    ImGui::EndCombo();
}

​
Advanced Usage

// Custom preview with multiple values
static bool selected[3] = { false, true, false };
char preview[64] = "";
if (selected[0]) strcat(preview, "Apple ");
if (selected[1]) strcat(preview, "Banana ");
if (selected[2]) strcat(preview, "Cherry ");

if (ImGui::BeginCombo("Multi-Select", preview)) {
    ImGui::Selectable("Apple", &selected[0]);
    ImGui::Selectable("Banana", &selected[1]);
    ImGui::Selectable("Cherry", &selected[2]);
    ImGui::EndCombo();
}

// With icons or custom rendering
if (ImGui::BeginCombo("Custom", "Preview")) {
    if (ImGui::Selectable("Item 1")) {
        // Selected
    }
    ImGui::SameLine();
    ImGui::TextDisabled("(hint)");
    
    if (ImGui::Selectable("Item 2")) {
        // Selected
    }
    ImGui::EndCombo();
}

// Searchable combo
static char search[128] = "";
if (ImGui::BeginCombo("Search", "Type to search")) {
    ImGui::SetKeyboardFocusHere();
    ImGui::InputText("##search", search, IM_COUNTOF(search));
    
    const char* items[] = { "Apple", "Apricot", "Banana", "Cherry" };
    for (int n = 0; n < IM_COUNTOF(items); n++) {
        if (search[0] == '\0' || strstr(items[n], search) != NULL) {
            if (ImGui::Selectable(items[n])) {
                // Selected
            }
        }
    }
    ImGui::EndCombo();
}

Build docs developers (and LLMs) love

Get started for freeTalk to us