How to Enable Gamepad Navigation in Dear ImGui

Enable gamepad navigation in Dear ImGui by setting the ImGuiConfigFlags_NavEnableGamepad flag in the ImGuiIO structure and ensuring your backend reports ImGuiBackendFlags_HasGamepad while forwarding gamepad button and axis events.

Dear ImGui provides full gamepad navigation support for menus, sliders, and window movement, but this feature requires explicit activation in your application code. According to the ocornut/imgui source code, the navigation system relies on two cooperating components: the global configuration flags set by your application and the backend's responsibility to detect and report controller state. This guide covers the specific implementation details using the official backends as reference.

Setting the Navigation Configuration Flag

The first step to enable gamepad navigation is configuring the ImGuiIO structure during initialization. In imgui.cpp, the ImGuiConfigFlags_NavEnableGamepad flag is defined to activate the navigation system.

Set this flag after creating your ImGui context:

ImGui::CreateContext();
ImGuiIO& io = ImGui::GetIO();
io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;  // Enable gamepad navigation

This flag tells Dear ImGui to process gamepad inputs for navigation actions such as directional movement, activation, and cancellation. However, the navigation system only becomes active when the backend confirms a gamepad is physically connected.

Backend Requirements for Gamepad Detection

Your platform backend must explicitly report gamepad presence by setting the ImGuiBackendFlags_HasGamepad flag in the io.BackendFlags field. The official Dear ImGui backends demonstrate this pattern across multiple platforms.

In backends/imgui_impl_glfw.cpp, the backend polls controller state and sets the flag when a gamepad is detected. Similarly, backends/imgui_impl_sdl2.cpp fills gamepad inputs and manages the backend flags regardless of the configuration state. For Windows applications, backends/imgui_impl_win32.cpp implements XInput support and sets the flag when controllers are available.

The backend must also forward input events using the io.AddKeyEvent() and io.AddKeyAnalogEvent() functions with the ImGuiKey_Gamepad_* key constants. For example:

• Digital buttons: ImGuiKey_GamepadFaceSouth, ImGuiKey_GamepadFaceEast, ImGuiKey_GamepadDpadLeft
• Analog sticks: ImGuiKey_GamepadLStickLeft, ImGuiKey_GamepadRStickUp

Complete Implementation Example

The following code demonstrates a complete initialization and frame loop setup using the GLFW backend:

// 1. Initialize ImGui context
ImGui::CreateContext();
ImGuiIO& io = ImGui::GetIO();

// 2. Enable gamepad navigation
io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;

// 3. Optional: Adjust button mapping (default: South = Activate, East = Cancel)
io.ConfigNavSwapGamepadButtons = false;

// Main application loop
while (!quit)
{
    // Platform-specific new frame preparation
    ImGui_ImplGlfw_NewFrame();
    ImGui::NewFrame();
    
    // Your UI code here
    ImGui::ShowDemoWindow();  // Displays navigation hints when active
    
    // Rendering
    ImGui::Render();
    ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
}

If you are implementing a custom backend, follow the pattern in imgui_impl_glfw.cpp: query the controller state each frame, call AddKeyEvent() for button presses, call AddKeyAnalogEvent() for stick movements, and set io.BackendFlags |= ImGuiBackendFlags_HasGamepad when a controller is connected.

Customizing Gamepad Behavior

Dear ImGui exposes configuration options to adjust how gamepad navigation behaves. The ImGuiIO structure provides the ConfigNavSwapGamepadButtons setting to swap the default activation and cancellation mapping.

By default:

• South button (A/Cross): Activate/Confirm
• East button (B/Circle): Cancel/Back

Set io.ConfigNavSwapGamepadButtons = true to reverse these actions for applications where East is the primary action button.

Verifying Gamepad Navigation

To confirm your implementation is working, open the demo window using ImGui::ShowDemoWindow(). In imgui_demo.cpp, the demo includes a Keyboard/Gamepad Navigation section that displays live status information and a checkbox to toggle the NavEnableGamepad flag dynamically.

When gamepad navigation is active, the UI displays navigation hints (for example, "South = Activate", "East = Cancel") to guide users. These visual indicators confirm that Dear ImGui is receiving gamepad input events from your backend.

Summary

• Set the configuration flag: Assign ImGuiConfigFlags_NavEnableGamepad to io.ConfigFlags during initialization as defined in imgui.cpp.
• Enable backend reporting: Ensure your backend sets ImGuiBackendFlags_HasGamepad and forwards events via AddKeyEvent() or AddKeyAnalogEvent().
• Reference official implementations: Study imgui_impl_glfw.cpp, imgui_impl_sdl2.cpp, or imgui_impl_win32.cpp for platform-specific gamepad handling.
• Customize mappings: Use ConfigNavSwapGamepadButtons to adjust activation button behavior.
• Test with demo: Use ImGui::ShowDemoWindow() to verify navigation hints and functionality.

Frequently Asked Questions

Why isn't my gamepad responding in Dear ImGui?

Your backend likely has not set the ImGuiBackendFlags_HasGamepad flag or is not calling AddKeyEvent() with ImGuiKey_Gamepad_* constants. Verify that your backend implementation follows the pattern in imgui_impl_glfw.cpp and that io.ConfigFlags includes ImGuiConfigFlags_NavEnableGamepad.

Do I need to write custom gamepad handling code?

If you use an official Dear ImGui backend (GLFW, SDL2, Win32), gamepad support is already implemented. You only need to enable the NavEnableGamepad flag. Custom backends require you to poll controller state and forward events using the ImGuiIO event functions.

Can users switch between gamepad and keyboard navigation?

Yes. Dear ImGui supports simultaneous keyboard and gamepad navigation. The navigation system processes inputs from both sources when NavEnableGamepad is set alongside the default keyboard navigation. Users can interact with the interface using whichever input method is most convenient.

Which gamepad models are compatible with Dear ImGui?

Dear ImGui uses standard XInput-style button mappings (South, East, North, West face buttons, D-pad, and analog sticks) as defined in the ImGuiKey_Gamepad_* enumeration. Any device that your backend can detect—whether through XInput, DirectInput, or platform-specific APIs—will work as long as the backend correctly maps physical buttons to these logical keys.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}