> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stac.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GestureDetector

> Documentation for GestureDetector

export const PLAYGROUND_BASE_URL = "https://playground.stac.dev/";

export const gestureDetectorPreviewJson = {
  "type": "gestureDetector",
  "child": {
    "type": "container",
    "color": "#2196F3",
    "width": 200,
    "height": 200,
    "alignment": "center",
    "child": {
      "type": "text",
      "data": "Tap me!",
      "style": {
        "color": "#FFFFFF",
        "fontSize": 20
      }
    }
  },
  "onTap": {
    "actionType": "showSnackBar",
    "content": {
      "type": "text",
      "data": "This is a Snackbar"
    }
  }
};
export const gestureDetectorPreviewSrc = `${PLAYGROUND_BASE_URL}/embed`;

The `GestureDetector` widget in Stac allows you to detect various gestures and user interactions within your application. It wraps Flutter's native GestureDetector widget, providing a JSON-based interface to handle touch events, taps, drags, and more.

## Usage

To use a GestureDetector in your Stac, specify the widget type as "gestureDetector" and provide a child widget along with any gesture callbacks you want to handle.

<Tabs sync={false}>
  <Tab title="Dart">
    ```dart theme={null}
    StacGestureDetector(
      child: StacContainer(
        color: StacColors.blue,
        width: 200,
        height: 200,
        alignment: StacAlignment.center,
        child: StacText(
          data: 'Tap me!',
          style: StacTextStyle(color: StacColors.white, fontSize: 20),
        ),
      ),
      onTap: StacSnackBarAction(
        content: StacText(data: 'This is a Snackbar'),
      ),
    )
    ```
  </Tab>

  <Tab title="JSON">
    ```json theme={null}
    {
      "type": "gestureDetector",
      "child": {
        "type": "container",
        "color": "#2196F3",
        "width": 200,
        "height": 200,
        "alignment": "center",
        "child": {
          "type": "text",
          "data": "Tap me!",
          "style": {
            "color": "#FFFFFF",
            "fontSize": 20
          }
        }
      },
      "onTap": {
        "actionType": "showSnackBar",
        "content": {
          "type": "text",
          "data": "This is a Snackbar"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Preview">
    <Frame>
      <iframe
        id="stac"
        src={gestureDetectorPreviewSrc}
        title="Stac Playground"
        className="w-full rounded-xl border-0"
        style={{ height: "640px" }}
        loading="lazy"
        onLoad={(event) => {
      const iframe = event.currentTarget;
      const targetOrigin = PLAYGROUND_BASE_URL;
      const message = {
        type: "stac-preview-json",
        payload: gestureDetectorPreviewJson
      };

      let attempts = 0;
      const maxAttempts = 12;
      const interval = setInterval(() => {
        iframe.contentWindow?.postMessage(message, targetOrigin);
        attempts += 1;

        if (attempts >= maxAttempts) {
          clearInterval(interval);
        }
      }, 250);
    }}
      />
    </Frame>
  </Tab>
</Tabs>

## Properties

### Child Widget

| Property | Type         | Description                              |
| -------- | ------------ | ---------------------------------------- |
| `child`  | `StacWidget` | The widget that will respond to gestures |

### Tap Gestures

| Property            | Type         | Description                                                         |
| ------------------- | ------------ | ------------------------------------------------------------------- |
| `onTapDown`         | `StacAction` | Called when a pointer contacts the screen                           |
| `onTapUp`           | `StacAction` | Called when a pointer stops contacting the screen                   |
| `onTap`             | `StacAction` | Called when a tap occurs                                            |
| `onTapCancel`       | `StacAction` | Called when the tap is canceled                                     |
| `onDoubleTapDown`   | `StacAction` | Called when a pointer contacts the screen in a potential double tap |
| `onDoubleTap`       | `StacAction` | Called when a double tap occurs                                     |
| `onDoubleTapCancel` | `StacAction` | Called when the double tap is canceled                              |

### Secondary and Tertiary Tap Gestures

| Property               | Type         | Description                                                 |
| ---------------------- | ------------ | ----------------------------------------------------------- |
| `onSecondaryTap`       | `StacAction` | Called when a secondary tap occurs (e.g., right-click)      |
| `onSecondaryTapDown`   | `StacAction` | Called when a secondary pointer contacts the screen         |
| `onSecondaryTapUp`     | `StacAction` | Called when a secondary pointer stops contacting the screen |
| `onSecondaryTapCancel` | `StacAction` | Called when the secondary tap is canceled                   |
| `onTertiaryTapDown`    | `StacAction` | Called when a tertiary pointer contacts the screen          |
| `onTertiaryTapUp`      | `StacAction` | Called when a tertiary pointer stops contacting the screen  |
| `onTertiaryTapCancel`  | `StacAction` | Called when the tertiary tap is canceled                    |

### Long Press Gestures

| Property                | Type         | Description                                                         |
| ----------------------- | ------------ | ------------------------------------------------------------------- |
| `onLongPressDown`       | `StacAction` | Called when a pointer contacts the screen in a potential long press |
| `onLongPressCancel`     | `StacAction` | Called when the long press is canceled                              |
| `onLongPress`           | `StacAction` | Called when a long press occurs                                     |
| `onLongPressStart`      | `StacAction` | Called when a long press starts                                     |
| `onLongPressMoveUpdate` | `StacAction` | Called when a long press move update occurs                         |
| `onLongPressUp`         | `StacAction` | Called when a long press up occurs                                  |
| `onLongPressEnd`        | `StacAction` | Called when a long press ends                                       |

### Secondary and Tertiary Long Press Gestures

| Property                         | Type         | Description                                                                   |
| -------------------------------- | ------------ | ----------------------------------------------------------------------------- |
| `onSecondaryLongPressDown`       | `StacAction` | Called when a secondary pointer contacts the screen in a potential long press |
| `onSecondaryLongPressCancel`     | `StacAction` | Called when the secondary long press is canceled                              |
| `onSecondaryLongPress`           | `StacAction` | Called when a secondary long press occurs                                     |
| `onSecondaryLongPressStart`      | `StacAction` | Called when a secondary long press starts                                     |
| `onSecondaryLongPressMoveUpdate` | `StacAction` | Called when a secondary long press move update occurs                         |
| `onSecondaryLongPressUp`         | `StacAction` | Called when a secondary long press up occurs                                  |
| `onSecondaryLongPressEnd`        | `StacAction` | Called when a secondary long press ends                                       |
| `onTertiaryLongPressDown`        | `StacAction` | Called when a tertiary pointer contacts the screen in a potential long press  |
| `onTertiaryLongPressCancel`      | `StacAction` | Called when the tertiary long press is canceled                               |
| `onTertiaryLongPress`            | `StacAction` | Called when a tertiary long press occurs                                      |
| `onTertiaryLongPressStart`       | `StacAction` | Called when a tertiary long press starts                                      |
| `onTertiaryLongPressMoveUpdate`  | `StacAction` | Called when a tertiary long press move update occurs                          |
| `onTertiaryLongPressUp`          | `StacAction` | Called when a tertiary long press up occurs                                   |
| `onTertiaryLongPressEnd`         | `StacAction` | Called when a tertiary long press ends                                        |

### Drag Gestures

| Property                 | Type         | Description                                                                 |
| ------------------------ | ------------ | --------------------------------------------------------------------------- |
| `onVerticalDragDown`     | `StacAction` | Called when a pointer contacts the screen and might begin a vertical drag   |
| `onVerticalDragStart`    | `StacAction` | Called when a pointer starts a vertical drag                                |
| `onVerticalDragUpdate`   | `StacAction` | Called when a pointer updates a vertical drag                               |
| `onVerticalDragEnd`      | `StacAction` | Called when a pointer ends a vertical drag                                  |
| `onVerticalDragCancel`   | `StacAction` | Called when the vertical drag is canceled                                   |
| `onHorizontalDragDown`   | `StacAction` | Called when a pointer contacts the screen and might begin a horizontal drag |
| `onHorizontalDragStart`  | `StacAction` | Called when a pointer starts a horizontal drag                              |
| `onHorizontalDragUpdate` | `StacAction` | Called when a pointer updates a horizontal drag                             |
| `onHorizontalDragEnd`    | `StacAction` | Called when a pointer ends a horizontal drag                                |
| `onHorizontalDragCancel` | `StacAction` | Called when the horizontal drag is canceled                                 |

### Force Press Gestures

| Property             | Type         | Description                                      |
| -------------------- | ------------ | ------------------------------------------------ |
| `onForcePressStart`  | `StacAction` | Called when a force press starts                 |
| `onForcePressPeak`   | `StacAction` | Called when a force press reaches its peak force |
| `onForcePressUpdate` | `StacAction` | Called when a force press updates                |
| `onForcePressEnd`    | `StacAction` | Called when a force press ends                   |

### Other Properties

| Property               | Type                    | Default | Description                                             |
| ---------------------- | ----------------------- | ------- | ------------------------------------------------------- |
| `excludeFromSemantics` | `bool`                  | `false` | Whether to exclude the gestures from the semantics tree |
| `dragStartBehavior`    | `StacDragStartBehavior` | `start` | Determines when a drag formally starts                  |

## Examples

### Simple Tap Example

<CodeGroup>
  ```dart Dart theme={null}
  StacGestureDetector(
    onTap: StacNavigateAction(routeName: '/details'),
    child: StacContainer(
      padding: StacEdgeInsets.all(16),
      color: StacColors.grey,
      child: StacText(data: 'Navigate to Details'),
    ),
  )
  ```

  ```json JSON theme={null}
  {
    "type": "gestureDetector",
    "onTap": {
      "actionType": "navigate",
      "routeName": "/details"
    },
    "child": {
      "type": "container",
      "padding": 16,
      "color": "#E0E0E0",
      "child": {
        "type": "text",
        "data": "Navigate to Details"
      }
    }
  }
  ```
</CodeGroup>

### Drag Example

<CodeGroup>
  ```dart Dart theme={null}
  StacGestureDetector(
    onHorizontalDragEnd: {'actionType': 'handleSwipe'},
    child: StacContainer(
      width: 200,
      height: 200,
      color: StacColors.grey,
      alignment: StacAlignment.center,
      child: StacText(data: 'Swipe horizontally'),
    ),
  )
  ```

  ```json JSON theme={null}
  {
    "type": "gestureDetector",
    "onHorizontalDragEnd": {
      "actionType": "handleSwipe"
    },
    "child": {
      "type": "container",
      "width": 200,
      "height": 200,
      "color": "#F5F5F5",
      "alignment": "center",
      "child": {
        "type": "text",
        "data": "Swipe horizontally"
      }
    }
  }
  ```
</CodeGroup>

### Long Press Example

<CodeGroup>
  ```dart Dart theme={null}
  StacGestureDetector(
    onLongPress: StacDialogAction(
      title: 'Long Press Detected',
      content: StacText(data: 'You performed a long press on the widget.'),
    ),
    child: StacContainer(
      padding: StacEdgeInsets.all(16),
      decoration: StacBoxDecoration(color: StacColors.green, borderRadius: StacBorderRadius.all(8)),
      child: StacText(
        data: 'Long press me',
        style: StacTextStyle(color: StacColors.white),
      ),
    ),
  )
  ```

  ```json JSON theme={null}
  {
    "type": "gestureDetector",
    "onLongPress": {
      "actionType": "showDialog",
      "title": "Long Press Detected",
      "content": "You performed a long press on the widget."
    },
    "child": {
      "type": "container",
      "padding": 16,
      "decoration": {
        "color": "#4CAF50",
        "borderRadius": 8
      },
      "child": {
        "type": "text",
        "data": "Long press me",
        "style": {
          "color": "#FFFFFF"
        }
      }
    }
  }
  ```
</CodeGroup>

## Action Handling

Each gesture callback in Stac GestureDetector accepts an action object that defines what should happen when the gesture is detected. This can be a navigation action, showing a dialog, executing a custom function, or any other action supported by your Stac application.

For more information on actions, see the [Actions documentation](/actions/navigate).