Gestures and scrolling

For AI agents: this page is Markdown at https://squiggle.sh/docs/flows/gestures.md. Every docs page is listed at https://squiggle.sh/llms.txt, and all of them are one file at https://squiggle.sh/llms-full.txt.

Swipe, scroll and drag in a flow, drag a sheet along a path in one touch, zoom with a double tap or a pinch, reach controls further down a list, and deal with a tap on a control that is off screen.

swipe and scroll go opposite ways

swipe names where your finger goes. scroll names where the content goes. To see what’s further down a list, you scroll: { direction: down }, and the finger moves up. Pick a step to see which way each one moves, and a position to see a drag to it:

The finger moves up, and you see items further down the list.

swipe says where the finger goes. scroll says which way you move through the content, like a mouse wheel. swipe: up and scroll: down are the same drag.

Drag to
YAML
- swipe: { testID: volume, to: 25% }

The drag starts at the slider’s centre and ends 25% of the way across its own width, so it lands on the same value on every screen size. Assert the value afterwards: a swipe that passes was sent, which is not the same as the slider moving.

YAML
- swipe: { direction: left }                   # the finger moves left- scroll: { direction: down, amount: 300 }      # shows 300 points more of what's below

amount is in points, 200 if you leave it out. A scroll holds the finger still before lifting it, so the content moves exactly that far, with no momentum. A swipe lifts while the finger is still moving, as a flick does, so a list keeps going and a sheet that closes on a fast swipe closes.

A swipe on a control waits until nothing on the screen is moving, as a tap does, so a swipe right after a sheet opens starts once the sheet has finished sliding in. A sheet ignores a drag while it is still opening. To close a sheet, swipe down on its heading, or on its list while the list is scrolled to the top. A swipe on a list that is not at its top scrolls the list instead, as your finger would:

YAML
- tap: { testID: open-filters }- swipe: { testID: filters-heading, direction: down, amount: 400 }- waitFor: { notVisible: { testID: filters-heading } }

On a React web app, swipes, scrolls, drags and pinches run as real input in Squiggle’s window. In a browser you opened yourself, they don’t; see React web apps.

Drag to a position

For a slider, a segmented control or a colour picker, the value is where the finger stops. A distance in points means something different on every device, so say where the drag ends instead, as a percentage of the control:

YAML
- swipe: { testID: brightness, to: 25% }        # a quarter of the way across- swipe: { testID: brightness, to: 100% }       # all the way right- swipe: { testID: canvas, to: "10%, 75%" }     # across and down

The drag starts at the control’s centre. One value sets how far across and keeps the finger centred vertically. Use either to or direction, not both. Then assert the new value: a swipe that passes only proves the drag was sent.

Drag after a long press

A list you reorder by holding a row and then dragging it only picks the row up after the finger has stayed still for a moment. A drag that moves at once scrolls the list instead. Add hold, in milliseconds, to press and hold before the drag starts. A held drag starts at the middle of the control you name and moves amount from there, so you pick up the row itself:

YAML
- swipe: { testID: row-milk, direction: down, amount: 88, hold: 400 }

Make hold longer than the list’s long-press delay. It takes a whole number from 1 to 3000, on a swipe or a drag but not on a scroll: a held finger picks something up, which is not a scroll. On a macOS app the step fails rather than drag without the hold.

Slow down a swipe or drag

A swipe takes about 300 milliseconds, as a flick does (on a React web app, a swipe that scrolls is quicker). Add duration, in milliseconds, to make the drag take longer. The finger also lifts more slowly, so a sheet that closes on a fast flick stays open unless the drag went far enough:

YAML
- swipe: { testID: sheet, direction: down, amount: 400, duration: 1500 }

It takes a whole number from 50 to 5000, on a swipe or on each leg of a drag (a pinch has its own, below), but not on a scroll: a scroll holds the finger still before it lifts, so its speed changes nothing. With hold, the hold comes first and duration times the drag after it.

To drag from one place to another at your own speed, use a drag with one leg. It starts on the control you name and ends at a place on the screen (see Drag along a path without lifting):

YAML
- drag:    from: { testID: sheet-handle }    path: [{ to: { y: 90% }, duration: 2000 }]

Swipe at a point when there is no control to name

A swipe with no selector runs across the middle of the screen. To swipe somewhere else, such as a map or a canvas, give a point in points or as a percentage of the screen, as on a tap. The swipe is centred on it:

YAML
- swipe: { point: "50%, 70%", direction: up, amount: 300 }

A swipe with a direction never starts in the top 60 points of the screen, the bottom 40 or the outer 20 on either side. On iOS a touch that starts there opens Notification Center or Control Center, goes to the home screen or goes back, instead of reaching your app. When a swipe would start there, it moves inward and keeps its amount. The finger can still end on an edge. A swipe with to or hold starts on its target wherever that is: it has to start on what it moves.

Besides its target, a swipe takes direction with amount, or to, and hold and duration. distance and from are refused with an error that names the field to use instead.

Drag along a path without lifting

A swipe is one straight move. To drag a bottom sheet down, back up and down again before you let go, use drag: the finger goes down at from, moves through every leg of path in order and lifts only after the last one. Between the legs the sheet follows the finger instead of settling:

YAML
- drag:    from: { testID: sheet-handle }    path:      - { to: { y: 75% }, duration: 1200 }   # down to 75% of the screen      - { to: { y: 40% }, duration: 1200 }   # back up to 40%      - { to: { y: 60% }, pause: 300 }       # down again, then hold still      - { to: { y: 100% } }                  # and all the way down
  • from is a selector, and the finger goes down at the point a tap on it would. If that control is off the screen, the step fails, as a tap does. A point string such as "50%, 60%", in points or percentages of the screen, puts the finger down there instead. Either way a drag never starts in the screen-edge bands a directional swipe avoids: a start there moves inward.
  • Each leg’s to is a place on the screen: "50%, 40%" as percentages of the screen, "120, 300" in points, or one axis on its own, such as { y: 40% }, which keeps the finger where it was on the other. A leg can end on an edge; one past it stops at the edge.
  • duration is how long the leg takes, from 50 to 5000 milliseconds (500 if you leave it out). pause holds the finger still at the end of the leg, up to 5000 milliseconds. End the last leg with a pause to let go with no flick.
  • hold presses still before the first leg, from 1 to 3000 milliseconds, as on a swipe. A path has 1 to 32 legs.

To pan a zoomed image or a map, drag it. For a quick flick, such as swiping a sheet away, use a swipe with a short duration. On a macOS app a drag can have only one leg and no hold; a longer path fails the step. When Replay drives the device, a recorded drag that turned back on the way runs again as one drag through every turn.

Pinch or double tap to zoom

doubleTap presses twice at the same point, quickly enough to count as a double tap. pinch puts two fingers on the control and moves them apart or together. scale is how far apart they end as a multiple of where they started: above 1 zooms in, below 1 zooms out.

YAML
- doubleTap: { testID: photo }              # zoom in where you tap- pinch: { testID: photo, scale: 3 }         # fingers apart: zoom in- drag:                                      # pan the zoomed photo    from: { testID: photo }    path: [{ to: { x: 20% }, duration: 600 }]- pinch: { testID: photo, scale: 0.3 }       # fingers together: zoom out
  • pinch takes a selector or a point, as a tap does, and fails on a control that is off the screen. scale takes 0.2 to 5, but not 1. The fingers move along a horizontal line through the control’s centre, at most 70% of its width apart and never closer than 40 points, so on a narrow control a large scale stops short of the full ratio.
  • duration is how long the fingers move, from 100 to 5000 milliseconds (400 if you leave it out).
  • A pinch, like a pan, reports only that it was sent. Assert the zoom your app shows afterwards.
  • On a macOS app, a pinch reaches only a Gesture Handler pinch and fails anywhere else, and a double tap is sent as two quick taps. On a React web app, both run as real input in Squiggle’s window.
  • When Replay drives the device, a recorded react-native-gesture-handler pinch runs again with the scale it had. A recording knows where the fingers were only within the view that was pinched, so a pinch on a view smaller than the screen replays shifted by that view’s distance from the top-left corner of the screen.

Pan a zoomed photo or flick it to dismiss

To pan a zoomed photo, drag it. To flick it away, use a fast swipe, such as swipe: { direction: down, amount: 300, duration: 120 }. A viewer that animates a photo in usually ignores gestures until it lands, so put a waitFor: { animationIdle: true } after opening it.

A swipe that registers as a tap

The gestures table in perf.db stores a touch outside react-native-gesture-handler as kind tap with dur_ms 0, at the point where the finger went down, even when the finger dragged. A tap row there doesn’t mean the swipe was sent as a tap. To check that a swipe moved something, assert what moved, such as the next page or the sheet’s position.

If your app’s pan didn’t move, check where the swipe started. A swipe with no selector runs across the middle of the screen, and one that would start on a screen edge starts further in. Name the control that pans, or give a point on it.

Scroll until a control appears

YAML
- scrollUntilVisible:    element: { text: Log out }    direction: down    maxScrolls: 10

scrollUntilVisible scrolls until the control is fully on screen and a tap at its centre would reach it, up to maxScrolls times (15 by default). If the control is already visible, it returns at once. If it still isn’t visible after the last scroll, the step fails with not visible after 15 scroll(s).

To cap how long it scrolls, add timeout in milliseconds, such as timeout: 10000. It stops at whichever of timeout and maxScrolls comes first, and fails with not visible within 10000ms.

Add mode: direct to move the list in one step instead of dragging, which is much faster. Leave it out when scrolling is what you’re testing: a direct scroll skips momentum, paging, snapping and pull-to-refresh. A direct scroll stops after maxScrolls only, and ignores timeout. To make direct the default for a run, see Run settings.

A tap on an off-screen control

When a tap or type targets a control outside the screen, the step fails and names the control’s position and the screen size. Squiggle won’t tap it anyway, because the tap would land on whatever is at the edge of the screen instead.

Add a scrollUntilVisible step before it. Or run with --auto-scroll, which scrolls the control into view and tries again, and marks the step scrolled into view. In Studio, it is Auto-scroll in the Flows screen’s Options menu.