# How to Enable Gamepad Navigation in Dear ImGui

> Learn to enable gamepad navigation in Dear ImGui. Set the NavEnableGamepad flag and forward input events for seamless controller support in your ImGui applications.

- Repository: [omar/imgui](https://github.com/ocornut/imgui)
- Tags: how-to-guide
- Published: 2026-07-30

---

**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`](https://github.com/ocornut/imgui/blob/main/imgui.cpp), the `ImGuiConfigFlags_NavEnableGamepad` flag is defined to activate the navigation system.

Set this flag after creating your ImGui context:

```cpp
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`](https://github.com/ocornut/imgui/blob/main/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`](https://github.com/ocornut/imgui/blob/main/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`](https://github.com/ocornut/imgui/blob/main/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:

```cpp
// 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`](https://github.com/ocornut/imgui/blob/main/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`](https://github.com/ocornut/imgui/blob/main/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`](https://github.com/ocornut/imgui/blob/main/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`](https://github.com/ocornut/imgui/blob/main/imgui_impl_glfw.cpp), [`imgui_impl_sdl2.cpp`](https://github.com/ocornut/imgui/blob/main/imgui_impl_sdl2.cpp), or [`imgui_impl_win32.cpp`](https://github.com/ocornut/imgui/blob/main/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`](https://github.com/ocornut/imgui/blob/main/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.