{
    "slug": "touch_events",
    "term": "Touch Events & Pointer Events",
    "category": "mobile",
    "difficulty": "intermediate",
    "short": "Handling touch input on mobile — the Pointer Events API unifies mouse, touch, and stylus into one event model, replacing the need for separate touch and mouse event handlers.",
    "long": "Touch Events (legacy): touchstart, touchmove, touchend — each has a touches list of all active contact points. Pointer Events (modern): pointerdown, pointermove, pointerup, pointercancel — single event model for mouse (pointerId=1), touch (multiple pointers), and stylus. Use Pointer Events in new code. Touch performance: passive event listeners (addEventListener('touchstart', fn, {passive: true})) tell the browser the listener won't call preventDefault(), allowing scroll optimisation without waiting for JS. 300ms click delay: eliminated in modern browsers; add touch-action: manipulation to CSS as a belt-and-braces fix.",
    "aliases": [
        "touch events",
        "pointer events",
        "touchstart",
        "pointerdown",
        "passive listener"
    ],
    "tags": [
        "mobile",
        "javascript",
        "performance"
    ],
    "misconception": "Click events work fine on mobile — click events on mobile have a 300ms delay on older browsers; click also doesn't fire for swipe gestures. Pointer Events provide immediate response and handle all input types.",
    "why_it_matters": "Non-passive touch event listeners block scrolling — the browser must wait for the JS handler before scrolling, causing jank on any page with touch listeners.",
    "common_mistakes": [
        "Non-passive touchstart/touchmove listeners — causes 50-200ms scroll delay.",
        "Using touchstart without touchend and touchcancel — incomplete gesture handling.",
        "Different code paths for touch and mouse — use Pointer Events for unified handling.",
        "Tap targets under 44x44px — too small for reliable touch input."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "js_custom_events",
        "mobile_performance",
        "web_vitals"
    ],
    "prerequisites": [
        "js_event_delegation",
        "js_custom_events",
        "progressive_enhancement"
    ],
    "refs": [
        "https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events"
    ],
    "bad_code": "// Blocks scroll — browser waits for JS before scrolling:\ndocument.addEventListener('touchstart', handleTouch);\n// Default: {passive: false} — browser must wait for JS\n\n// Separate mouse and touch handlers — maintenance burden:\nelement.addEventListener('click', handler);\nelement.addEventListener('touchstart', handler);",
    "good_code": "// Pointer Events — unified, immediate:\ndocument.addEventListener('pointerdown', e => {\n    if (e.pointerType === 'touch') handleTouch(e);\n    else handleMouse(e);\n});\n\n// Passive scroll listener — does not block scrolling:\ndocument.addEventListener('touchmove', handleMove, { passive: true });\n\n/* CSS — eliminate 300ms delay: */\n/* button, a { touch-action: manipulation; } */\n\n// Multi-touch:\ndocument.addEventListener('pointerdown', e => {\n    activePointers.set(e.pointerId, e); // Track each finger\n});",
    "quick_fix": "Use Pointer Events API instead of Touch Events — it handles mouse, touch, and stylus with one API; add touch-action: none CSS to elements that handle their own touch to prevent browser interference",
    "severity": "low",
    "effort": "medium",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/touch_events",
        "html_url": "https://codeclaritylab.com/glossary/touch_events",
        "json_url": "https://codeclaritylab.com/glossary/touch_events.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Touch Events & Pointer Events](https://codeclaritylab.com/glossary/touch_events) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/touch_events"
            }
        }
    }
}