Flutter JoyButtons

Pub License Pub likes Pub popularity Pub points Flutter platform

Virtual JoyButtons for Flutter touchscreen apps. Inspired by programming Gravitar for smartphones and needing shield and bullets simultaneously.

Run the example app in your web or mobile browser


Virtual JoyButtons are a way to press multiple game buttons simultaneously. Physical game controllers allow simultaneous presses by different fingers. A touchscreen device is limited to front facing touchscreens which make simultaneous button pressing a real challenge.

JoyButtons to the rescue. The user uses one thumb and can active multiple buttons simultaneously, just not in all possible combinations for large number of buttons. There are any number of buttons outside a center button. Like a virtual joystick, the user can move their thumb around the two dimensions. If the thumb is pressing over the center area, the centerButtonOutput is reported. The center presses are customizable by the programmer. If the thumb is pressing in the JoyButtons outside the center area, then presses are reported for one or two adjacent buttons. This is also customizable. When the thumb is not pressing, an empty list of buttons is reported.

default buttons 5 buttons 2 buttons


  • activate one button, two buttons, or all buttons simultaneously with a single thumb or finger.
  • press and drag with one thumb, callback which buttons are currently pressed.
  • inspired by Gravitar which needs shields and firing simultaneously without lifting a thumb.

Shoutout to flutter_joystick for usage and code inspiration. Gravitar uses flutter_joystick for mobile.


flutter_joybuttons uses by default 4 JoyButtonsButton or you can pass a list of one or more JoyButtonsButton. The example lets you change how many are used. There can be a large amount of buttons defined. Just note the more buttons there are, the less angular difference between buttons. 2 to 5 buttons seem reasonable.

The example shows 3 buttons setup. The center area report all 3 buttons when pressed. The outer buttons can activate simultaneously with an adjacent button or alone. In the example, pressing the outer area and sweeping around 360 degrees will activate 1 or 2 buttons simultaneously, while moving to the center button will activate all buttons. You can define which buttons are reported when pressing the center - any List

Between the outer buttons, the area between buttons that reports multiple button activation is customizeable by simultaneousOverlapScale. A value of 0.0 means no overlap area so only single buttons are activated while pressing in the outer area. A value of 1.0 means that the overlap is 100% into the adjacent buttons, so there are always multiple activations while pressing in the outer area. The default value is 0.4.


  • buttonWidgets: the List
  • simultaneousOverlapScale from 0.0 (alone) to 1.0 (always with an adjacent) or alone and with an adjacent (default of about 0.4).
  • centerButton: a Widget for the center button.
  • centerButtonOutput: List