0121. on:swipe, and the gesture parts built on it
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-15
- Decided by: domain E fixer (internal only), after the review of PR #36
- Amends: 0108
Context
Decision 0108 cut PullToRefresh, swipe row actions, Drawer and DateRangePicker from the kit, because the language had no way to hear a swipe. The review asked for all four as real parts, and for the Pager to page on a swipe. Each needed one thing the language lacked: a quick move across an element, with its direction, heard the same way on the web and on a phone.
Decision
**on:swipe, an event on <view>.** It runs when a finger, or a mouse or pen held down, moves at least 40 px across the element, at least one and a half times as far along one axis as across it, and lifts within 800 ms. The handler receives { direction: "left" | "right" | "up" | "down" }.
- A swipe down counts only from the top. While what scrolls around the element is scrolled at all, a swipe down is a scroll back up and is not reported. This is what lets PullToRefresh never refresh a feed that is being scrolled back up. On the web every scrolling ancestor and the page are checked; on native the nearest
<screen>or<scroll>tells its children how far it is scrolled (aScrollTopcontext, from eachbindscroll). - A swipe is not also a press. On the web the click a mouse swipe ends with is swallowed, wherever it lands; a touch swipe makes none. On native Lynx sends no tap for a moved touch.
- Where it is heard: on the web, touch events (which still end when the browser scrolls) and pointer events for a mouse or pen, ended on the window so a swipe may end off the element; the element keeps horizontal moves (
touch-action: pan-y) and its text is not selected by a mouse swipe. On native, Lynx'sbindtouchstart,bindtouchendandbindtouchcancel, joined with the view's press handlers so both hear a touch. - Never the only way. The spec says every swipe needs another way to do the same thing, and every kit part that uses one has it: a button, a key, or both.
The parts.
| Part | The swipe | The other way |
|---|---|---|
| Pager | Left moves on, right back | Previous, Next and the dots |
| SwipeRow | Left shows the actions, right puts them away | Its More button (aria-expanded), then each action is a button |
| PullToRefresh | Down from the top refreshes | Its Refresh button; a spinner and a status say it is refreshing |
| Drawer | Left on the panel closes it | Escape, the scrim, its Close button; it is a modal dialog overlay, so focus moves in, stays and returns |
| DateRangePicker | None: it is DatePicker's grid choosing a start, then an end | Every key DatePicker has |
Alternatives considered
| Option | Why not |
|---|---|
An on:refresh event on <scroll>, from overscroll | Lynx reports bindscrolltoupper only once at the top, not a pull; the browser reports no overscroll at all. A swipe down from the top is the same gesture, heard the same way on both. |
| A drag that follows the finger, with the offset as motion | Needs a per-frame position the language has no way to hand to a style; the sheet's drag (decision 0034) is built into its overlay kind. A swipe is enough for each part's job, and its result is animated by the part's own motion. |
A drawer overlay kind | A dialog overlay laid out as a row with the panel at its start does the same, and keeps the overlay kinds as they are. |
Consequences
spec/language/elements.yamllistson:swipeon<view>; the grammars and references are generated from it. The adapter gainsSwipeEventandViewProps.onSwipe.- The web runtime ships
web/swipe; the native onesrc/swipe.ts. - Right-to-left layouts are not mirrored yet: a Drawer stays on the left and closes on a swipe left, and SwipeRow's actions come from the right. Mirroring them needs the layout direction, which neither runtime reports to a page yet.
- A real finger's fling, and how VoiceOver and TalkBack read the parts, are checked on a device (
native/DEVICE-CHECKLIST.md); the browser tests drive the swipes with real touch events.