> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# swipe

> Swipe or scroll a surface in a direction or between two points.

The `swipe` action moves a virtual finger (or pointer) across a browser or app surface. Use it when your documentation walks the reader through a gesture that [`find`](find) can't infer. That covers carousels, onboarding pagers, pull-to-refresh, sliders, and plain "scroll down to see more."

`swipe` is the movement subset of [`dragAndDrop`](draganddrop). `dragAndDrop` locates two elements and moves between them, while `swipe` moves between two points. You author those points directly, or Doc Detective computes them from a direction shorthand.

**The direction is the finger's motion.** Swiping `up` moves content up, revealing content further down the page. That's the gesture you make to read more. Swiping `left` reveals content to the right, such as the next carousel card.

## Forms

**String shorthand.** Swipe up on the active browser tab:

```json
{ "swipe": "up" }
```

**Directional.** Swipe 80% of the app window's height:

```json
{ "swipe": { "direction": "up", "distance": 0.8, "surface": { "app": "myapp" } } }
```

**Point-to-point.** Drag from one point to another:

```json
{ "swipe": { "from": { "x": 200, "y": 600 }, "to": { "x": 200, "y": 200 }, "duration": 400 } }
```

Point coordinates are pixels from the surface's top-left corner. That origin is the app window for app surfaces and the viewport for browsers, matching the pixel convention of browser `window` and `viewport` sizing. The directional form's `distance` stays a fraction of the surface, so directional swipes are portable across window sizes without knowing pixels.

## Properties

| Property     | Type             | Description                                                                                                                                                                                                                                                                                                                               |
| ------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `direction`  | string           | The finger's motion: `up`, `down`, `left`, or `right`. Directional form only.                                                                                                                                                                                                                                                             |
| `distance`   | number           | How far to swipe, as a fraction (0–1] of the surface's height (up/down) or width (left/right). Default: `0.5`. Directional form only.                                                                                                                                                                                                     |
| `from`, `to` | object           | `{ "x": px, "y": px }` pixel coordinates (from the surface's top-left) where the finger presses down and releases. Point-to-point form only, and mutually exclusive with `direction` and `distance`.                                                                                                                                      |
| `duration`   | integer          | Movement time in milliseconds. Default: `500`.                                                                                                                                                                                                                                                                                            |
| `surface`    | string or object | The browser or app surface to swipe. Omit to act on the active surface (the most recently opened, focused, or explicitly targeted browser tab or app window). App surfaces use the object form (`{ "app": "…" }`). On Windows/macOS, add a `window` selector to swipe a specific window of the app (see [App windows](find#app-windows)). |

See the [swipe schema reference](/reference/schemas/swipe) for the full shapes.

## Surface behavior

* **Mobile app surfaces (Android/iOS)**: a real touch gesture through the device driver. Directional swipes stay inside a 10%-inset box so a full-length swipe can't trigger a system edge gesture (Android back/home).
* **Desktop app surfaces (Windows/macOS)**: a directional swipe scrolls the window with a mouse wheel at the window center. Dragging a desktop window's content doesn't scroll it. A point-to-point swipe is a real click-and-drag.
* **Browser surfaces**: a directional swipe scrolls the page with `window.scrollBy` under finger-motion semantics. A mouse drag on a web page selects text instead of scrolling. A point-to-point swipe is a real pointer drag, which suits sliders, canvases, and maps. Point-to-point needs the W3C actions endpoint, so like non-left-button clicks it's desktop-browser-only for now.
* **Process surfaces**: not applicable. A background process has no screen to swipe, and the schema doesn't accept one.

> **Info**
>
> A browser directional swipe *scrolls*. It doesn't synthesize touch events. A web carousel driven by touch listeners won't respond. Test it on a mobile app surface, or drive it with a point-to-point swipe if it also handles pointer drags.

> **Tip**
>
> You usually don't need to swipe merely to bring an element into view before a [`find`](find). `find` auto-scrolls on mobile app surfaces, and scrolls into view on browsers. Reach for `swipe` when the gesture itself is what the documentation describes.