JavaScript Reference ยท DOM: Events
Touch and gesture events
Reference for touchstart, touchmove, touchend and touchcancel, the TouchEvent and Touch objects, multi-touch lists and why pointer events are usually better.
Touch events report fingers on a touch screen. Four events cover a touch's life: touchstart when a finger lands, touchmove while it moves, touchend when it lifts, and touchcancel when the browser interrupts the touch (for example when it takes over for scrolling or a system gesture).
Each event is a TouchEvent with lists of Touch objects, one per finger. This makes multi-touch possible, but the API is touch-only. For new code, most pages are better served by pointer events (pointerdown, pointermove, pointerup), which cover mouse, pen and touch with one set of handlers. Touch events remain useful for multi-finger handling and for older code.
surface.addEventListener("touchstart", (event) => { for (const touch of event.changedTouches) { console.log(touch.identifier, touch.clientX, touch.clientY); } }, { passive: true });
Try it
Syntax
element.addEventListener("touchstart", listener, { passive: true });
TouchEvent properties
| Name | Description |
|---|---|
touches |
A list of every finger currently on the screen, on any element. |
targetTouches |
Only the fingers that started on the event's target element. |
changedTouches |
The fingers that changed in this event: the ones that landed, moved or lifted. |
shiftKey, ctrlKey, altKey, metaKey |
Modifier key state. |
Touch properties
| Name | Description |
|---|---|
identifier |
A number that stays the same for one finger from touchstart to touchend. |
clientX, clientY |
Position relative to the viewport. pageX/pageY and screenX/screenY are also available. |
target |
The element where this touch started, even if the finger has moved away. |
radiusX, radiusY, force |
Contact size and pressure, where the device reports them. |
Usage notes
- A lifted finger is no longer in
touches. Intouchendandtouchcancelthe finger that left appears only inchangedTouches, so read its final position there. - Match fingers by
identifier, not by array index. Indexes change as fingers come and go. - Passive by default. Browsers treat
touchstartandtouchmovelisteners onwindow,documentandbodyas passive. A passive listener cannot callpreventDefault(). To block scrolling use CSStouch-action: none(preferred) or add{ passive: false }. See passive listeners. - Touches also produce mouse events. After a tap, browsers fire compatibility
mousedown,mouseupandclickevents. CallingpreventDefault()ontouchstartortouchendsuppresses them. touchcancelmust be handled. Treat it liketouchendwithout the action, or your UI can get stuck in a "pressed" state.- Detecting touch.
"ontouchstart" in windowtells you the API exists, not that the user has a touch screen.navigator.maxTouchPointsis a better hint, but laptops can have both mouse and touch. Handle both input types instead of choosing one. - Gesture events.
gesturestart,gesturechangeandgestureend(pinch and rotate) exist only in Safari and are non-standard. For cross-browser pinch and zoom, track two pointers or two touches yourself and compute the distance and angle. - Prefer pointer events for new code: one code path, built-in capture with
setPointerCapture(), andpointerTypeto tell mouse, pen and touch apart.
Browser support
Touch events work on touch-capable browsers, including mobile browsers and desktop browsers on touch screens. Gesture events are a Safari-only, non-standard feature. Pointer events are supported in all current browsers.
Related
- click and pointer events
- passive listeners
- scroll and wheel events
- drag and drop events
navigatorโmaxTouchPoints- Lesson: Events