Keyboard Input

Functions for checking keyboard state and key presses

Overview

Dear ImGui uses the ImGuiKey enum which contains all possible keyboard, mouse, and gamepad inputs. The keyboard key enum values are named after the keys on a standard US keyboard.

Consider using the Shortcut() function instead of IsKeyPressed()/IsKeyChordPressed()! Shortcut() is easier to use and better featured (supports focus routing).

Key State Functions

IsKeyDown

bool IsKeyDown(ImGuiKey key);

Check if key is being held.

key · ImGuiKey

Key to check (e.g., ImGuiKey_A, ImGuiKey_Space)

Returns · bool

True if key is currently down

Example:

if (ImGui::IsKeyDown(ImGuiKey_LeftCtrl))
{
    ImGui::Text("Ctrl is being held");
}

IsKeyPressed

bool IsKeyPressed(ImGuiKey key, bool repeat = true);

Check if key was pressed (went from !Down to Down).

key · ImGuiKey

Key to check

repeat · bool · default: "true"

If true, returns true on key repeat. Repeat rate uses io.KeyRepeatDelay / io.KeyRepeatRate.

Returns · bool

True if key was just pressed or repeating

Example:

if (ImGui::IsKeyPressed(ImGuiKey_Enter))
{
    SubmitForm();
}

// Without repeat
if (ImGui::IsKeyPressed(ImGuiKey_Space, false))
{
    FireWeapon();
}

IsKeyReleased

bool IsKeyReleased(ImGuiKey key);

Check if key was released (went from Down to !Down).

key · ImGuiKey

Key to check

Returns · bool

True if key was just released

GetKeyPressedAmount

int GetKeyPressedAmount(ImGuiKey key, float repeat_delay, float rate);

Get a count of key presses using provided repeat rate/delay. Usually returns 0 or 1 but might be >1 if RepeatRate is small enough that DeltaTime > RepeatRate.

key · ImGuiKey

Key to check

repeat_delay · float

Time before repeat starts

rate · float

Repeat rate

Returns · int

Number of key presses this frame

Example:

int presses = ImGui::GetKeyPressedAmount(ImGuiKey_DownArrow, 0.02f, 0.02f);
selection_index = (selection_index + presses) % item_count;

Key Chords

IsKeyChordPressed

bool IsKeyChordPressed(ImGuiKeyChord key_chord);

Check if a key chord (mods + key) was pressed. This doesn’t do any routing or focus check.

key_chord · ImGuiKeyChord

Key chord (e.g., ImGuiMod_Ctrl | ImGuiKey_S)

Returns · bool

True if the key chord was pressed

Consider using Shortcut() instead, which supports focus routing and is more feature-complete.

Example:

if (ImGui::IsKeyChordPressed(ImGuiMod_Ctrl | ImGuiKey_S))
{
    SaveDocument();
}

if (ImGui::IsKeyChordPressed(ImGuiMod_Ctrl | ImGuiMod_Shift | ImGuiKey_Z))
{
    Redo();
}

Key Names

GetKeyName

const char* GetKeyName(ImGuiKey key);

Get English name of the key for debugging purposes.

key · ImGuiKey

Key to get name for

Returns · const char*

Key name string

These names are provided for debugging purposes and are not meant to be saved persistently nor compared.

Example:

ImGui::Text("Press %s to continue", ImGui::GetKeyName(ImGuiKey_Enter));

Keyboard Capture

SetNextFrameWantCaptureKeyboard

void SetNextFrameWantCaptureKeyboard(bool want_capture_keyboard);

Override io.WantCaptureKeyboard flag next frame. Equivalent to setting io.WantCaptureKeyboard after the next NewFrame() call.

want_capture_keyboard · bool

Whether to capture keyboard

Example:

// Force capture keyboard when widget is hovered
if (ImGui::IsItemHovered())
{
    ImGui::SetNextFrameWantCaptureKeyboard(true);
}

ImGuiKey Enum

enum ImGuiKey : int
{
    // Keyboard
    ImGuiKey_None = 0,
    ImGuiKey_Tab = 512,
    ImGuiKey_LeftArrow, ImGuiKey_RightArrow, ImGuiKey_UpArrow, ImGuiKey_DownArrow,
    ImGuiKey_PageUp, ImGuiKey_PageDown,
    ImGuiKey_Home, ImGuiKey_End,
    ImGuiKey_Insert, ImGuiKey_Delete,
    ImGuiKey_Backspace, ImGuiKey_Space, ImGuiKey_Enter, ImGuiKey_Escape,
    
    // Modifiers
    ImGuiKey_LeftCtrl, ImGuiKey_LeftShift, ImGuiKey_LeftAlt, ImGuiKey_LeftSuper,
    ImGuiKey_RightCtrl, ImGuiKey_RightShift, ImGuiKey_RightAlt, ImGuiKey_RightSuper,
    ImGuiKey_Menu,
    
    // Numbers
    ImGuiKey_0, ImGuiKey_1, ImGuiKey_2, ImGuiKey_3, ImGuiKey_4,
    ImGuiKey_5, ImGuiKey_6, ImGuiKey_7, ImGuiKey_8, ImGuiKey_9,
    
    // Letters
    ImGuiKey_A, ImGuiKey_B, ImGuiKey_C, ImGuiKey_D, ImGuiKey_E, ImGuiKey_F,
    ImGuiKey_G, ImGuiKey_H, ImGuiKey_I, ImGuiKey_J, ImGuiKey_K, ImGuiKey_L,
    ImGuiKey_M, ImGuiKey_N, ImGuiKey_O, ImGuiKey_P, ImGuiKey_Q, ImGuiKey_R,
    ImGuiKey_S, ImGuiKey_T, ImGuiKey_U, ImGuiKey_V, ImGuiKey_W, ImGuiKey_X,
    ImGuiKey_Y, ImGuiKey_Z,
    
    // Function keys
    ImGuiKey_F1, ImGuiKey_F2, ImGuiKey_F3, ImGuiKey_F4,
    ImGuiKey_F5, ImGuiKey_F6, ImGuiKey_F7, ImGuiKey_F8,
    ImGuiKey_F9, ImGuiKey_F10, ImGuiKey_F11, ImGuiKey_F12,
    
    // Symbols
    ImGuiKey_Apostrophe,    // '
    ImGuiKey_Comma,         // ,
    ImGuiKey_Minus,         // -
    ImGuiKey_Period,        // .
    ImGuiKey_Slash,         // /
    ImGuiKey_Semicolon,     // ;
    ImGuiKey_Equal,         // =
    ImGuiKey_LeftBracket,   // [
    ImGuiKey_Backslash,     // \
    ImGuiKey_RightBracket,  // ]
    ImGuiKey_GraveAccent,   // `
    
    // Lock keys
    ImGuiKey_CapsLock, ImGuiKey_ScrollLock, ImGuiKey_NumLock,
    ImGuiKey_PrintScreen, ImGuiKey_Pause,
    
    // Keypad
    ImGuiKey_Keypad0, ImGuiKey_Keypad1, ImGuiKey_Keypad2,
    ImGuiKey_Keypad3, ImGuiKey_Keypad4, ImGuiKey_Keypad5,
    ImGuiKey_Keypad6, ImGuiKey_Keypad7, ImGuiKey_Keypad8, ImGuiKey_Keypad9,
    ImGuiKey_KeypadDecimal, ImGuiKey_KeypadDivide,
    ImGuiKey_KeypadMultiply, ImGuiKey_KeypadSubtract,
    ImGuiKey_KeypadAdd, ImGuiKey_KeypadEnter, ImGuiKey_KeypadEqual,
    
    // Gamepad (see full list in imgui.h)
    ImGuiKey_GamepadStart, ImGuiKey_GamepadBack,
    ImGuiKey_GamepadFaceLeft, ImGuiKey_GamepadFaceRight,
    ImGuiKey_GamepadFaceUp, ImGuiKey_GamepadFaceDown,
    // ...
    
    // Mouse buttons (aliased for convenience)
    ImGuiKey_MouseLeft, ImGuiKey_MouseRight, ImGuiKey_MouseMiddle,
    ImGuiKey_MouseX1, ImGuiKey_MouseX2,
    ImGuiKey_MouseWheelX, ImGuiKey_MouseWheelY,
};

Keyboard Modifiers

enum
{
    ImGuiMod_None   = 0,
    ImGuiMod_Ctrl   = 1 << 12,  // Ctrl (non-macOS), Cmd (macOS)
    ImGuiMod_Shift  = 1 << 13,  // Shift
    ImGuiMod_Alt    = 1 << 14,  // Alt/Option
    ImGuiMod_Super  = 1 << 15,  // Windows/Super (non-macOS), Ctrl (macOS)
};

On macOS, Dear ImGui swaps Cmd(Super) and Ctrl keys at the time of io.AddKeyEvent() call.

Key Data Structure

struct ImGuiKeyData
{
    bool    Down;               // True if key is down
    float   DownDuration;       // Duration key has been down (<0: not pressed, 0: just pressed, >0: time held)
    float   DownDurationPrev;   // Last frame duration
    float   AnalogValue;        // 0.0f..1.0f for gamepad values
};

Access via:

ImGuiIO& io = ImGui::GetIO();
ImGuiKeyData* key_data = &io.KeysData[key - ImGuiKey_NamedKey_BEGIN];
if (key_data->Down) { /* ... */ }

MUST use key - ImGuiKey_NamedKey_BEGIN as index when accessing KeysData[].

Common Patterns

Check Multiple Keys

if (ImGui::IsKeyDown(ImGuiKey_LeftCtrl) && ImGui::IsKeyPressed(ImGuiKey_C))
{
    CopyToClipboard();
}

Smooth Movement with Keys

float speed = 100.0f * ImGui::GetIO().DeltaTime;
if (ImGui::IsKeyDown(ImGuiKey_W)) position.y -= speed;
if (ImGui::IsKeyDown(ImGuiKey_S)) position.y += speed;
if (ImGui::IsKeyDown(ImGuiKey_A)) position.x -= speed;
if (ImGui::IsKeyDown(ImGuiKey_D)) position.x += speed;

Key Repeat for UI Navigation

if (ImGui::IsKeyPressed(ImGuiKey_UpArrow))
{
    selected_index = (selected_index - 1 + item_count) % item_count;
}
if (ImGui::IsKeyPressed(ImGuiKey_DownArrow))
{
    selected_index = (selected_index + 1) % item_count;
}

See Also

• Mouse - Mouse input functions
• Shortcuts - Keyboard shortcuts and input routing
• Input - General input and ImGuiIO functions