Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
surface.addEventListener("touchstart", (event) => {
  for (const touch of event.changedTouches) {
    console.log(touch.identifier, touch.clientX, touch.clientY);
  }
}, { passive: true });

Try it

Detect touch support and log touches
Pointer events: one handler for mouse, pen and touch

Syntax

JavaScript
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. In touchend and touchcancel the finger that left appears only in changedTouches, 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 touchstart and touchmove listeners on window, document and body as passive. A passive listener cannot call preventDefault(). To block scrolling use CSS touch-action: none (preferred) or add { passive: false }. See passive listeners.
  • Touches also produce mouse events. After a tap, browsers fire compatibility mousedown, mouseup and click events. Calling preventDefault() on touchstart or touchend suppresses them.
  • touchcancel must be handled. Treat it like touchend without the action, or your UI can get stuck in a "pressed" state.
  • Detecting touch. "ontouchstart" in window tells you the API exists, not that the user has a touch screen. navigator.maxTouchPoints is a better hint, but laptops can have both mouse and touch. Handle both input types instead of choosing one.
  • Gesture events. gesturestart, gesturechange and gestureend (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(), and pointerType to 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.