In Flame, add TapCallbacks or DragCallbacks to the component that should react to touch. Add KeyboardEvents to the game for keys. Add a JoystickComponent for an on-screen stick, and GamepadCallbacks from flame_gamepads for controllers. One game can use all four.

This is for Flutter developers who want one game to work on a phone, a laptop and a controller. It uses flame 1.38.2, the latest stable version in October 2026.

In short:

  • Touch events go to the component under the finger, and stop there by default.
  • A component with zero size cannot be touched.
  • Keyboard handling lives on the game, or on components with extra setup.
  • Put joysticks and buttons in camera.viewport so they stay still.

Touch goes to the component you touched

Per Flame's tap events page, the TapCallbacks mixin adds onTapDown, onTapUp, onTapCancel and onLongTapDown. The event goes to the first component at the touch point that has the mixin, then stops, unless you set event.continuePropagation = true.

A tap that turns into a drag ends with onTapCancel. Every component that got onTapDown later gets either onTapUp or onTapCancel.

class Coin extends CircleComponent with TapCallbacks {
              Coin() : super(radius: 16);
            
              @override
              void onTapDown(TapDownEvent event) => removeFromParent();
            }
            

event.localPosition is relative to the component and event.canvasPosition is on the whole canvas. Several fingers work at once, and pointerId tells them apart.

Drags need a wide target

DragCallbacks gives onDragStart, onDragUpdate, onDragEnd and onDragCancel. The component only receives a drag that starts inside it. The Flame 1.38.1 changelog also notes that a drag now needs the touch slop distance before it is accepted.

For "drag anywhere to steer", cover the whole field with one invisible component, as in the dodge game. Use event.localDelta to move the player by how far the finger moved.

Components must have a size. The tap and drag pages both say the component needs containsLocalPoint, which PositionComponent provides from its size.

Keyboard events live on the game

For desktop and web, mix KeyboardEvents into the game and override onKeyEvent.

class DodgeGame extends FlameGame with KeyboardEvents {
              @override
              KeyEventResult onKeyEvent(KeyEvent event, Set<LogicalKeyboardKey> keys) {
                final left = keys.contains(LogicalKeyboardKey.arrowLeft);
                final right = keys.contains(LogicalKeyboardKey.arrowRight);
                player.direction = (right ? 1 : 0) - (left ? 1 : 0);
                return KeyEventResult.handled;
              }
            }
            

The player then moves x += direction * 200 * dt in its update. Storing a direction and applying it every frame gives smooth movement, where reacting to each key event would stutter.

Return handled when Flame used the key, and ignored to let other widgets try. If a key is not handled by anything, some platforms play a system alert sound.

To handle keys inside components, use the KeyboardHandler mixin and give the game HasKeyboardHandlerComponents. The docs warn to remove KeyboardEvents then, to avoid conflicts. GameWidget focuses itself by default (autofocus: true). If another widget steals focus, pass your own focusNode.

A joystick is one component

For phones, JoystickComponent draws a stick and exposes direction, delta and relativeDelta (the pull as a share of the stick's range, with direction).

final joystick = JoystickComponent(
              knob: CircleComponent(
                  radius: 20, paint: Paint()..color = Colors.white70),
              background: CircleComponent(
                  radius: 50, paint: Paint()..color = Colors.white24),
              margin: const EdgeInsets.only(left: 30, bottom: 30),
            );
            camera.viewport.add(joystick);
            

In the player's update, read joystick.relativeDelta.x * speed * dt when joystick.direction is not JoystickDirection.idle. The viewport is the right parent, because its children stay put while the world scrolls. HudButtonComponent works the same way for buttons placed by margin from the viewport edge.

Gamepads come from a bridge package

flame_gamepads (0.1.2 in October 2026) wraps the gamepads package. Mix GamepadCallbacks into a component and override onGamepadEvent(NormalizedGamepadEvent event). Check event.button == GamepadButton.a && event.value != 0 for a press. The docs link an example in the Flame repository.

The version number is low, so test on your target hardware before you promise controller support.

Choose input by device

Give each device the input it was made for, plus one backup.

Device Primary input Backup
Phone Drag zone or joystick Tap buttons
Laptop or web Arrow keys Mouse drag
Console-style Gamepad Keyboard

Because a mouse click is reported like a touch, drag and tap code already works with a mouse on desktop and web. Add the keyboard on top.

Add arrow keys in 10 minutes

Take the dodge game, add with KeyboardEvents to the game, and store direction on the player. Hold the left arrow in the browser and the square should slide. Then read about Flame menus and overlays to add a pause button.

Sources and further reading