JavaScript Document createTouchList() Method

What You’ll Learn

document.createTouchList() is a deprecated, non-standard instance method that once built a TouchList from zero or more Touch objects (see MDN Document: createTouchList()). Learn MDN’s empty / one / many examples, how it pairs with createTouch(), safe feature detection, and five try-it labs that still work when the API is missing.

Introduction

A TouchList is a list of active finger contacts — the kind of collection you normally read from touchstart / touchmove via event.touches or event.changedTouches.

Legacy engines also exposed document.createTouchList(...) so scripts could assemble those lists by hand (often after createTouch()). MDN now labels both helpers deprecated and non-standard.

Related tutorials: createTouch(), createEvent(), JavaScript hub.

Understanding document.createTouchList()

An instance method on Document that builds a TouchList from the Touch arguments you pass (MDN).

• Purpose (legacy) — create a TouchList object (MDN).
• Parameters — zero or more Touch objects (MDN).
• Firefox note — MDN: Firefox also accepted an array of Touch objects.
• Return value — a TouchList containing those touches (MDN).
• Empty list — createTouchList() with no args (MDN example).
• Support reality — often removed; feature-detect every time.

📝 Syntax

General forms of Document.createTouchList (MDN):

createTouchList(touch1)
createTouchList(touch1, touch2)
createTouchList(touch1, touch2, /* …, */ touchN)

Parameters

• touch1, …, touchN — zero or more Touch objects (MDN). Firefox also accepted an array of Touch objects (MDN).

Return value

A TouchList object containing the Touch objects specified (MDN).

Exceptions

None highlighted on MDN for the method itself. Calling a missing method throws TypeError — always feature-detect.

MDN example

const target = document.getElementById("target");

const touch1 = document.createTouch(window, target, 1, 15, 20, 35, 40);
const touch2 = document.createTouch(window, target, 2, 25, 30, 45, 50);

const list0 = document.createTouchList();
const list1 = document.createTouchList(touch1);
const list2 = document.createTouchList(touch1, touch2);

⚖️ Legacy createTouchList vs modern input lists

Examples Gallery

Examples follow MDN Document: createTouchList() and safe feature-detection. On many desktops the method is missing — that is expected.

const supported = typeof document.createTouchList === "function";
console.log(supported ? "createTouchList available (legacy)" : "createTouchList missing");

if (!supported) {
  console.log("Prefer event.touches / Pointer Events for real UI.");
}

createTouchList missing
Prefer event.touches / Pointer Events for real UI.

const target = document.getElementById("target");
const hasList = typeof document.createTouchList === "function";
const hasTouch = typeof document.createTouch === "function";

if (!hasList || !hasTouch) {
  console.log("legacy touch factories not available");
} else {
  const touch1 = document.createTouch(window, target, 1, 15, 20, 35, 40);
  const touch2 = document.createTouch(window, target, 2, 25, 30, 45, 50);
  const list0 = document.createTouchList();
  const list1 = document.createTouchList(touch1);
  const list2 = document.createTouchList(touch1, touch2);
  console.log(list0.length, list1.length, list2.length); // 0 1 2
}

legacy touch factories not available

if (
  typeof document.createTouchList !== "function" ||
  typeof document.createTouch !== "function"
) {
  console.log("skipped — APIs missing");
} else {
  const t = document.createTouch(window, document.body, 9, 10, 20, 30, 40);
  const list = document.createTouchList(t);
  console.log(list.length);           // 1
  console.log(list.item(0).identifier); // 9
}

skipped — APIs missing

console.log("createTouchList:", typeof document.createTouchList);

document.addEventListener("touchstart", (event) => {
  console.log("changedTouches.length:", event.changedTouches.length);
}, { once: true });

console.log("On desktop, try Pointer Events (pointerdown) instead.");

createTouchList: undefined
On desktop, try Pointer Events (pointerdown) instead.

const touchOk = typeof document.createTouch === "function";
const listOk = typeof document.createTouchList === "function";

console.log("createTouch:", touchOk);
console.log("createTouchList:", listOk);
console.log(
  touchOk && listOk
    ? "legacy pair present (still avoid in new apps)"
    : "migrate — use real touch / pointer events"
);

createTouch: false
createTouchList: false
migrate — use real touch / pointer events

🚀 Common Use Cases

• Reading legacy samples — understand old synthetic touch tests.
• Migrating old code — replace factories with real event lists.
• Interview trivia — know it is deprecated and non-standard (MDN).
• Not for new apps — use touch* events or Pointer Events.
• Paired with createTouch — usually removed or kept together.
• Not a mobile detector — never treat presence as “is phone”.

📝 Notes

• MDN: Deprecated and Non-standard.
• Not part of any current specification; not on track to become a standard (MDN).
• Accepts zero or more Touch objects; Firefox also accepted an array (MDN).
• Often used with createTouch() in legacy samples.
• Feature-detect before calling — many modern engines omit it.
• Related learning: createTouch(), createEvent(), JavaScript hub.

💡 Best Practices