Skip to main content

​
Selectable Widgets

A selectable highlights when hovered, and can display another color when selected. Neighbors selectable extend their highlight bounds in order to leave no gap between them.

​
Selectable

bool ImGui::Selectable(const char* label, bool selected = false, ImGuiSelectableFlags flags = 0, const ImVec2& size = ImVec2(0, 0))
Selectable widget. selected carries the selection state (read-only). Returns true when clicked.
​
label
const char*
Selectable label
​
selected
bool
default:"false"
Current selection state (read-only)
​
flags
ImGuiSelectableFlags
default:"0"
Selectable flags (see ImGuiSelectableFlags_)
​
size
const ImVec2&
default:"ImVec2(0, 0)"
Size (0.0f = use remaining width/height, >0.0f = specify)
​
return
bool
True when clicked (modify your selection state)
// Example
static int selected = -1;
for (int n = 0; n < 10; n++) {
    char buf[32];
    sprintf(buf, "Object %d", n);
    if (ImGui::Selectable(buf, selected == n)) {
        selected = n;
    }
}

​
Selectable (pointer)

bool ImGui::Selectable(const char* label, bool* p_selected, ImGuiSelectableFlags flags = 0, const ImVec2& size = ImVec2(0, 0))
Selectable with pointer to selection state (read-write), as a convenient helper.
​
label
const char*
Selectable label
​
p_selected
bool*
Pointer to selection state (read-write)
​
flags
ImGuiSelectableFlags
default:"0"
Selectable flags
​
size
const ImVec2&
default:"ImVec2(0, 0)"
Size
​
return
bool
True when clicked
// Example
static bool selection[5] = { false, false, false, false, false };
for (int n = 0; n < 5; n++) {
    char buf[32];
    sprintf(buf, "Object %d", n);
    ImGui::Selectable(buf, &selection[n]);
}

​
Multi-Selection

Multi-selection system for Selectable(), Checkbox(), TreeNode() functions. This enables standard multi-selection/range-selection idioms (Ctrl+Mouse/Keyboard, Shift+Mouse/Keyboard, etc.).

​
BeginMultiSelect

ImGuiMultiSelectIO* ImGui::BeginMultiSelect(ImGuiMultiSelectFlags flags, int selection_size = -1, int items_count = -1)
Begin multi-selection scope.
​
flags
ImGuiMultiSelectFlags
Multi-select flags (see ImGuiMultiSelectFlags_)
​
selection_size
int
default:"-1"
Current number of selected items (-1 if expensive to compute)
​
items_count
int
default:"-1"
Total number of items (-1 if expensive to compute)
​
return
ImGuiMultiSelectIO*
Multi-select I/O structure with requests to apply
// Example
static ImGuiSelectionBasicStorage selection;
ImGuiMultiSelectIO* ms_io = ImGui::BeginMultiSelect(ImGuiMultiSelectFlags_None, selection.Size, items.Size);
// Apply selection requests
for (int n = 0; n < items.Size; n++) {
    ImGui::SetNextItemSelectionUserData(n);
    bool is_selected = selection.Contains((ImGuiID)n);
    ImGui::Selectable(items[n].Name, is_selected);
}
ms_io = ImGui::EndMultiSelect();
// Apply post-selection requests

​
EndMultiSelect

ImGuiMultiSelectIO* ImGui::EndMultiSelect()
End multi-selection scope.
​
return
ImGuiMultiSelectIO*
Multi-select I/O structure with post-loop requests

​
SetNextItemSelectionUserData

void ImGui::SetNextItemSelectionUserData(ImGuiSelectionUserData selection_user_data)
Set selection user data for the next item. This is typically an item index within your current view.
​
selection_user_data
ImGuiSelectionUserData
User data (typically item index)

​
IsItemToggledSelection

bool ImGui::IsItemToggledSelection()
Was the last item selection state toggled? Useful if you need the per-item information before reaching EndMultiSelect().
​
return
bool
True if item selection was toggled

​
Selectable Flags

​
ImGuiSelectableFlags_

Flags for Selectable().
FlagDescription
ImGuiSelectableFlags_NoneDefault
ImGuiSelectableFlags_NoAutoClosePopupsClicking this doesn’t close parent popup window
ImGuiSelectableFlags_SpanAllColumnsFrame will span all columns of container table
ImGuiSelectableFlags_AllowDoubleClickGenerate press events on double clicks too
ImGuiSelectableFlags_DisabledCannot be selected, display grayed out text
ImGuiSelectableFlags_AllowOverlapHit testing to allow subsequent widgets to overlap
ImGuiSelectableFlags_HighlightMake the item be displayed as if it is hovered
ImGuiSelectableFlags_SelectOnNavAuto-select when moved into (unless Ctrl is held)
// Examples

// Span all columns in a table
if (ImGui::BeginTable("table", 3)) {
    for (int row = 0; row < 5; row++) {
        ImGui::TableNextRow();
        ImGui::TableNextColumn();
        ImGui::Selectable("Row", false, ImGuiSelectableFlags_SpanAllColumns);
    }
    ImGui::EndTable();
}

// Disabled selectable
ImGui::Selectable("Disabled", false, ImGuiSelectableFlags_Disabled);

// Allow double-click
if (ImGui::Selectable("Double-click me", false, ImGuiSelectableFlags_AllowDoubleClick)) {
    if (ImGui::IsMouseDoubleClicked(0)) {
        // Double-clicked
    }
}

// Highlight
ImGui::Selectable("Highlighted", false, ImGuiSelectableFlags_Highlight);

​
Multi-Select Flags

​
ImGuiMultiSelectFlags_

Flags for BeginMultiSelect().
FlagDescription
ImGuiMultiSelectFlags_NoneDefault
ImGuiMultiSelectFlags_SingleSelectSingle selection mode (default is multi-select)
ImGuiMultiSelectFlags_NoSelectAllDisable select all (Ctrl+A)
ImGuiMultiSelectFlags_NoRangeSelectDisable range select (Shift+Click)
ImGuiMultiSelectFlags_NoAutoSelectDisable auto-select on navigation
ImGuiMultiSelectFlags_NoAutoClearDisable auto-clear on click in empty space
ImGuiMultiSelectFlags_NoAutoClearOnReselectDisable auto-clear when re-clicking selected item
ImGuiMultiSelectFlags_BoxSelect1dEnable 1D box-select (within a single axis)
ImGuiMultiSelectFlags_BoxSelect2dEnable 2D box-select
ImGuiMultiSelectFlags_BoxSelectNoScrollDisable scrolling when box-selecting
ImGuiMultiSelectFlags_ClearOnEscapeClear selection on Escape key
ImGuiMultiSelectFlags_ClearOnClickVoidClear selection when clicking in void
// Single selection mode
ImGuiMultiSelectIO* ms_io = ImGui::BeginMultiSelect(ImGuiMultiSelectFlags_SingleSelect);
// ...
ImGui::EndMultiSelect();

// Disable Ctrl+A
ms_io = ImGui::BeginMultiSelect(ImGuiMultiSelectFlags_NoSelectAll);
// ...
ImGui::EndMultiSelect();

​
List Boxes

List boxes are thin wrappers around BeginChild() with the ImGuiChildFlags_FrameStyle flag.

​
BeginListBox

bool ImGui::BeginListBox(const char* label, const ImVec2& size = ImVec2(0, 0))
Open a framed scrolling region. Only call EndListBox() if BeginListBox() returns true.
​
label
const char*
List box label
​
size
const ImVec2&
default:"ImVec2(0, 0)"
Size (0 = default size)
​
return
bool
True if list box is open
// Example
const char* items[] = { "Apple", "Banana", "Cherry", "Kiwi", "Mango", "Orange", "Pineapple", "Strawberry", "Watermelon" };
static int item_current = 1;

if (ImGui::BeginListBox("Items")) {
    for (int n = 0; n < IM_COUNTOF(items); n++) {
        const bool is_selected = (item_current == n);
        if (ImGui::Selectable(items[n], is_selected)) {
            item_current = n;
        }
        if (is_selected) {
            ImGui::SetItemDefaultFocus();
        }
    }
    ImGui::EndListBox();
}

​
EndListBox

void ImGui::EndListBox()
Close list box. Only call if BeginListBox() returned true.

​
ListBox (simple)

bool ImGui::ListBox(const char* label, int* current_item, const char* const items[], int items_count, int height_in_items = -1)
Simple list box helper.
​
label
const char*
List 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
​
height_in_items
int
default:"-1"
Height in number of items (-1 = default ~7)
​
return
bool
True when selection has been modified
// Example
const char* items[] = { "Apple", "Banana", "Cherry" };
static int item_current = 1;
ImGui::ListBox("Fruits", &item_current, items, IM_COUNTOF(items), 4);

​
ListBox (callback)

bool ImGui::ListBox(const char* label, int* current_item, const char* (*getter)(void* user_data, int idx), void* user_data, int items_count, int height_in_items = -1)
List box with callback to get item strings.
​
label
const char*
List box label
​
current_item
int*
Pointer to current selected item index
​
getter
const char* (*)(void*, int)
Callback function to get item string
​
user_data
void*
User data passed to callback
​
items_count
int
Number of items
​
height_in_items
int
default:"-1"
Height in number of items
​
return
bool
True when selection has been modified

Build docs developers (and LLMs) love

Get started for freeTalk to us