# flutter_joystick
**Repository Path**: jiaxin_wei/flutter_joystick
## Basic Information
- **Project Name**: flutter_joystick
- **Description**: A virtual joystick for Flutter applications. Highly flexible and customizable.
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-28
- **Last Updated**: 2025-04-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Flutter Joystick
[](https://pub.dev/packages/flutter_joystick)
[](https://github.com/pavelzaichyk/flutter_joystick/blob/master/LICENSE)
[](https://pub.dev/packages/flutter_joystick/score)
[](https://pub.dev/packages/flutter_joystick/score)
[](https://pub.dev/packages/flutter_joystick/score)
[](https://pub.dev/packages/flutter_joystick)
[](https://www.buymeacoffee.com/rebeloid)
[](https://paypal.me/pavelzaichyk)
Flutter Joystick is a virtual joystick package for Flutter applications that provides interactive
joystick components for user interface design.
[See Examples](https://joystick.rebeloid.com)
[Google Play](https://play.google.com/store/apps/details?id=com.rebeloid.flutter_joystick_example)
## Table of Contents
- [Joystick](#joystick)
- [Joystick Area](#joystick-area)
- [Customization](#customization)
- [Donate](#donate)
- [Contributors](#contributors)
### Joystick
The `Joystick` widget is a virtual joystick that allows users to drag a stick within a defined area.
You can customize its behavior and appearance. Here's how you can use it:
```dart
Joystick(listener: (details) {
...
})
```
**`Joystick` Arguments:**
| Parameter | Description |
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `listener` | A callback function that is invoked at a specified frequency (`period`) when the joystick stick is dragged. The `listener` parameter, `details`, provides the stick's offset from the center of the base (ranging from -1.0 to +1.0). |
| `period` | (Optional) The frequency at which the `listener` callback is triggered from the moment the stick is dragged. The default is 100 milliseconds. |
| `mode` | (Optional) The possible direction mode of the joystick stick. The default mode is `all`, allowing movement in any direction: vertical, horizontal, and diagonal. |
| `includeInitialAnimation` | (Optional) Decides if the stick's initial movement animation should be included. By default [true]. |
This information clarifies the purpose and usage of each parameter for the `Joystick` widget.
| Mode | Description |
|-------------------------|--------------------------------------------------------------------------------------------------------|
| `all` | Allows movement of the joystick stick in any direction: vertical, horizontal, and diagonal. |
| `vertical` | Restricts movement of the joystick stick to the vertical direction only. |
| `horizontal` | Restricts movement of the joystick stick to the horizontal direction only. |
| `horizontalAndVertical` | Restricts movement of the joystick stick to both horizontal and vertical directions, but not diagonal. |
These modes define how the joystick stick can be moved, providing flexibility in tailoring the
joystick's behavior to specific requirements.
### Joystick Area
The `JoystickArea` widget allows you to render a joystick anywhere within a designated area when the
user interacts with it. It shares similar properties with the `Joystick` widget.
```dart
JoystickArea(
listener: (details) {
...
},
child: ...
)
```
**Additional `JoystickArea` Arguments:**
| Parameter | Description |
|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `initialJoystickAlignment` | (Optional) Sets the initial alignment of the joystick within the joystick area. By default, it is aligned to `Alignment.bottomCenter`. |
| `child` | (Optional) The widget that is contained within the joystick area, allowing you to place other elements or widgets alongside the joystick. |
These arguments provide additional customization options for the `JoystickArea` widget, allowing you
to control the initial alignment and include child widgets for a more versatile user interface.
### Customization
**Customization Options:**
The `Joystick` and `JoystickArea` widgets are highly customizable, allowing you to tailor their appearance and behavior to fit your application's unique requirements. Below are the parameters you can adjust:
| Parameter | Description |
|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `base` | (Optional) The widget responsible for rendering the joystick's base. By default, it uses `JoystickBase`, but you can replace it with any widget to change its look. For example, you can use a custom image or a different shape. |
| `stick` | (Optional) The widget that defines the appearance of the joystick stick. It is centered within the `base` widget. The default is `JoystickStick`, but you can customize it to be any widget, such as an icon, image, or animated widget. |
| `stickOffsetCalculator` | (Optional) A function that determines the stick's offset based on the starting position of the stick drag and its current position. The package supports circular and rectangular shapes through `CircleStickOffsetCalculator` and `RectangleStickOffsetCalculator` respectively. You can create custom offset calculators for other shapes. |
These customization parameters empower you to create distinctive and unique joystick experiences for
your Flutter applications.
**Examples:**
| Code | Example |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| Joystick(
base: JoystickBase(
decoration: JoystickBaseDecoration(
middleCircleColor: Colors.red.shade400,
drawOuterCircle: false,
drawInnerCircle: false,
boxShadowColor: Colors.red.shade100,
),
),
stick: JoystickStick(
decoration: JoystickStickDecoration(
color: Colors.red,
),
),
listener: (details) {..},
)
|  |
| Joystick(
base: JoystickBase(
decoration: JoystickBaseDecoration(
color: Colors.black,
drawOuterCircle: false,
),
arrowsDecoration: JoystickArrowsDecoration(
color: Colors.blue,
),
),
listener: (details) {..},
)
|  |
| Joystick(
includeInitialAnimation: false,
base: JoystickBase(
decoration: JoystickBaseDecoration(
color: Colors.orange,
),
arrowsDecoration: JoystickArrowsDecoration(
color: Colors.grey,
enableAnimation: false,
),
),
stick: JoystickStick(
decoration: JoystickStickDecoration(
color: Colors.grey,
shadowColor: Colors.white.withOpacity(0.5)
),
),
listener: (details) {..},
)
|  |
| Joystick(
base: JoystickSquareBase(),
stickOffsetCalculator: const RectangleStickOffsetCalculator(),
listener: (details) {..},
)
|  |
| Joystick(
stick: const CircleAvatar(
radius: 30,
child: FlutterLogo(size: 50),
),
base: Container(
width: 200,
height: 200,
decoration: const BoxDecoration(
color: Colors.grey,
shape: BoxShape.circle,
),
),
listener: (details) {..},
)
|  |
These examples highlight the flexibility of the joystick widget and provide a foundation for you to create your own customized joystick designs.
## Donate
If you find this package helpful and would like to support its continued development, please consider making a donation. Your contributions are greatly appreciated and motivate the further enhancement of this and other plugins.
[](https://www.paypal.com/donate/?hosted_button_id=QE4E8RX8FW6P4)
[](https://www.buymeacoffee.com/rebeloid)
[](https://paypal.me/pavelzaichyk)
Your support helps in maintaining and improving this package, ensuring it remains up-to-date and useful for the community.
Thank you for your generosity!
## Contributors