5 * @preserve FastClick: polyfill to remove click delays on browsers with touch UIs.
7 * @codingstandard ftlabs-jsv2
8 * @copyright The Financial Times Limited [All Rights Reserved]
9 * @license MIT License (see LICENSE.txt)
12 /*jslint browser:true, node:true*/
13 /*global define, Event, Node*/
17 * Instantiate fast-clicking listeners on the specified layer.
20 * @param {Element} layer The layer to listen on
21 * @param {Object} [options={}] The options to override the defaults
23 function FastClick(layer, options) {
26 options = options || {};
29 * Whether a click is currently being tracked.
33 this.trackingClick = false;
37 * Timestamp for when click tracking started.
41 this.trackingClickStart = 0;
45 * The element being tracked for a click.
49 this.targetElement = null;
53 * X-coordinate of touch start event.
61 * Y-coordinate of touch start event.
69 * ID of the last touch, retrieved from Touch.identifier.
73 this.lastTouchIdentifier = 0;
77 * Touchmove boundary, beyond which a click will be cancelled.
81 this.touchBoundary = options.touchBoundary || 10;
85 * The FastClick layer.
92 * The minimum time between tap(touchstart and touchend) events
96 this.tapDelay = options.tapDelay || 200;
99 * The maximum time for a tap
103 this.tapTimeout = options.tapTimeout || 700;
105 if (FastClick.notNeeded(layer)) {
109 // Some old versions of Android don't have Function.prototype.bind
110 function bind(method, context) {
111 return function() { return method.apply(context, arguments); };
115 var methods = ['onMouse', 'onClick', 'onTouchStart', 'onTouchMove', 'onTouchEnd', 'onTouchCancel'];
117 for (var i = 0, l = methods.length; i < l; i++) {
118 context[methods[i]] = bind(context[methods[i]], context);
121 // Set up event handlers as required
122 if (deviceIsAndroid) {
123 layer.addEventListener('mouseover', this.onMouse, true);
124 layer.addEventListener('mousedown', this.onMouse, true);
125 layer.addEventListener('mouseup', this.onMouse, true);
128 layer.addEventListener('click', this.onClick, true);
129 layer.addEventListener('touchstart', this.onTouchStart, false);
130 layer.addEventListener('touchmove', this.onTouchMove, false);
131 layer.addEventListener('touchend', this.onTouchEnd, false);
132 layer.addEventListener('touchcancel', this.onTouchCancel, false);
134 // Hack is required for browsers that don't support Event#stopImmediatePropagation (e.g. Android 2)
135 // which is how FastClick normally stops click events bubbling to callbacks registered on the FastClick
136 // layer when they are cancelled.
137 if (!Event.prototype.stopImmediatePropagation) {
138 layer.removeEventListener = function(type, callback, capture) {
139 var rmv = Node.prototype.removeEventListener;
140 if (type === 'click') {
141 rmv.call(layer, type, callback.hijacked || callback, capture);
143 rmv.call(layer, type, callback, capture);
147 layer.addEventListener = function(type, callback, capture) {
148 var adv = Node.prototype.addEventListener;
149 if (type === 'click') {
150 adv.call(layer, type, callback.hijacked || (callback.hijacked = function(event) {
151 if (!event.propagationStopped) {
156 adv.call(layer, type, callback, capture);
161 // If a handler is already declared in the element's onclick attribute, it will be fired before
162 // FastClick's onClick handler. Fix this by pulling out the user-defined handler function and
163 // adding it as listener.
164 if (typeof layer.onclick === 'function') {
166 // Android browser on at least 3.2 requires a new reference to the function in layer.onclick
167 // - the old one won't work if passed to addEventListener directly.
168 oldOnClick = layer.onclick;
169 layer.addEventListener('click', function(event) {
172 layer.onclick = null;
177 * Windows Phone 8.1 fakes user agent string to look like Android and iPhone.
181 var deviceIsWindowsPhone = navigator.userAgent.indexOf("Windows Phone") >= 0;
184 * Android requires exceptions.
188 var deviceIsAndroid = navigator.userAgent.indexOf('Android') > 0 && !deviceIsWindowsPhone;
192 * iOS requires exceptions.
196 var deviceIsIOS = /iP(ad|hone|od)/.test(navigator.userAgent) && !deviceIsWindowsPhone;
200 * iOS 4 requires an exception for select elements.
204 var deviceIsIOS4 = deviceIsIOS && (/OS 4_\d(_\d)?/).test(navigator.userAgent);
208 * iOS 6.0-7.* requires the target element to be manually derived
212 var deviceIsIOSWithBadTarget = deviceIsIOS && (/OS [6-7]_\d/).test(navigator.userAgent);
215 * BlackBerry requires exceptions.
219 var deviceIsBlackBerry10 = navigator.userAgent.indexOf('BB10') > 0;
222 * Determine whether a given element requires a native click.
224 * @param {EventTarget|Element} target Target DOM element
225 * @returns {boolean} Returns true if the element needs a native click
227 FastClick.prototype.needsClick = function(target) {
228 switch (target.nodeName.toLowerCase()) {
230 // Don't send a synthetic click to disabled inputs (issue #62)
234 if (target.disabled) {
241 // File inputs need real clicks on iOS 6 due to a browser bug (issue #68)
242 if ((deviceIsIOS && target.type === 'file') || target.disabled) {
248 case 'iframe': // iOS8 homescreen apps can prevent events bubbling into frames
253 return (/\bneedsclick\b/).test(target.className);
258 * Determine whether a given element requires a call to focus to simulate click into element.
260 * @param {EventTarget|Element} target Target DOM element
261 * @returns {boolean} Returns true if the element requires a call to focus to simulate native click.
263 FastClick.prototype.needsFocus = function(target) {
264 switch (target.nodeName.toLowerCase()) {
268 return !deviceIsAndroid;
270 switch (target.type) {
280 // No point in attempting to focus disabled inputs
281 return !target.disabled && !target.readOnly;
283 return (/\bneedsfocus\b/).test(target.className);
289 * Send a click event to the specified element.
291 * @param {EventTarget|Element} targetElement
292 * @param {Event} event
294 FastClick.prototype.sendClick = function(targetElement, event) {
295 var clickEvent, touch;
297 // On some Android devices activeElement needs to be blurred otherwise the synthetic click will have no effect (#24)
298 if (document.activeElement && document.activeElement !== targetElement) {
299 document.activeElement.blur();
302 touch = event.changedTouches[0];
304 // Synthesise a click event, with an extra attribute so it can be tracked
305 clickEvent = document.createEvent('MouseEvents');
306 clickEvent.initMouseEvent(this.determineEventType(targetElement), true, true, window, 1, touch.screenX, touch.screenY, touch.clientX, touch.clientY, false, false, false, false, 0, null);
307 clickEvent.forwardedTouchEvent = true;
308 targetElement.dispatchEvent(clickEvent);
311 FastClick.prototype.determineEventType = function(targetElement) {
313 //Issue #159: Android Chrome Select Box does not open with a synthetic click event
314 if (deviceIsAndroid && targetElement.tagName.toLowerCase() === 'select') {
323 * @param {EventTarget|Element} targetElement
325 FastClick.prototype.focus = function(targetElement) {
328 // Issue #160: on iOS 7, some input elements (e.g. date datetime month) throw a vague TypeError on setSelectionRange. These elements don't have an integer value for the selectionStart and selectionEnd properties, but unfortunately that can't be used for detection because accessing the properties also throws a TypeError. Just check the type instead. Filed as Apple bug #15122724.
329 if (deviceIsIOS && targetElement.setSelectionRange && targetElement.type.indexOf('date') !== 0 && targetElement.type !== 'time' && targetElement.type !== 'month') {
330 length = targetElement.value.length;
331 targetElement.setSelectionRange(length, length);
333 targetElement.focus();
339 * Check whether the given target element is a child of a scrollable layer and if so, set a flag on it.
341 * @param {EventTarget|Element} targetElement
343 FastClick.prototype.updateScrollParent = function(targetElement) {
344 var scrollParent, parentElement;
346 scrollParent = targetElement.fastClickScrollParent;
348 // Attempt to discover whether the target element is contained within a scrollable layer. Re-check if the
349 // target element was moved to another parent.
350 if (!scrollParent || !scrollParent.contains(targetElement)) {
351 parentElement = targetElement;
353 if (parentElement.scrollHeight > parentElement.offsetHeight) {
354 scrollParent = parentElement;
355 targetElement.fastClickScrollParent = parentElement;
359 parentElement = parentElement.parentElement;
360 } while (parentElement);
363 // Always update the scroll top tracker if possible.
365 scrollParent.fastClickLastScrollTop = scrollParent.scrollTop;
371 * @param {EventTarget} targetElement
372 * @returns {Element|EventTarget}
374 FastClick.prototype.getTargetElementFromEventTarget = function(eventTarget) {
376 // On some older browsers (notably Safari on iOS 4.1 - see issue #56) the event target may be a text node.
377 if (eventTarget.nodeType === Node.TEXT_NODE) {
378 return eventTarget.parentNode;
386 * On touch start, record the position and scroll offset.
388 * @param {Event} event
391 FastClick.prototype.onTouchStart = function(event) {
392 var targetElement, touch, selection;
394 // Ignore multiple touches, otherwise pinch-to-zoom is prevented if both fingers are on the FastClick element (issue #111).
395 if (event.targetTouches.length > 1) {
399 targetElement = this.getTargetElementFromEventTarget(event.target);
400 touch = event.targetTouches[0];
404 // Only trusted events will deselect text on iOS (issue #49)
405 selection = window.getSelection();
406 if (selection.rangeCount && !selection.isCollapsed) {
412 // Weird things happen on iOS when an alert or confirm dialog is opened from a click event callback (issue #23):
413 // when the user next taps anywhere else on the page, new touchstart and touchend events are dispatched
414 // with the same identifier as the touch event that previously triggered the click that triggered the alert.
415 // Sadly, there is an issue on iOS 4 that causes some normal touch events to have the same identifier as an
416 // immediately preceeding touch event (issue #52), so this fix is unavailable on that platform.
417 // Issue 120: touch.identifier is 0 when Chrome dev tools 'Emulate touch events' is set with an iOS device UA string,
418 // which causes all touch events to be ignored. As this block only applies to iOS, and iOS identifiers are always long,
419 // random integers, it's safe to to continue if the identifier is 0 here.
420 if (touch.identifier && touch.identifier === this.lastTouchIdentifier) {
421 event.preventDefault();
425 this.lastTouchIdentifier = touch.identifier;
427 // If the target element is a child of a scrollable layer (using -webkit-overflow-scrolling: touch) and:
428 // 1) the user does a fling scroll on the scrollable layer
429 // 2) the user stops the fling scroll with another tap
430 // then the event.target of the last 'touchend' event will be the element that was under the user's finger
431 // when the fling scroll was started, causing FastClick to send a click event to that layer - unless a check
432 // is made to ensure that a parent layer was not scrolled before sending a synthetic click (issue #42).
433 this.updateScrollParent(targetElement);
437 this.trackingClick = true;
438 this.trackingClickStart = event.timeStamp;
439 this.targetElement = targetElement;
441 this.touchStartX = touch.pageX;
442 this.touchStartY = touch.pageY;
444 // Prevent phantom clicks on fast double-tap (issue #36)
445 if ((event.timeStamp - this.lastClickTime) < this.tapDelay) {
446 event.preventDefault();
454 * Based on a touchmove event object, check whether the touch has moved past a boundary since it started.
456 * @param {Event} event
459 FastClick.prototype.touchHasMoved = function(event) {
460 var touch = event.changedTouches[0], boundary = this.touchBoundary;
462 if (Math.abs(touch.pageX - this.touchStartX) > boundary || Math.abs(touch.pageY - this.touchStartY) > boundary) {
471 * Update the last position.
473 * @param {Event} event
476 FastClick.prototype.onTouchMove = function(event) {
477 if (!this.trackingClick) {
481 // If the touch has moved, cancel the click tracking
482 if (this.targetElement !== this.getTargetElementFromEventTarget(event.target) || this.touchHasMoved(event)) {
483 this.trackingClick = false;
484 this.targetElement = null;
492 * Attempt to find the labelled control for the given label element.
494 * @param {EventTarget|HTMLLabelElement} labelElement
495 * @returns {Element|null}
497 FastClick.prototype.findControl = function(labelElement) {
499 // Fast path for newer browsers supporting the HTML5 control attribute
500 if (labelElement.control !== undefined) {
501 return labelElement.control;
504 // All browsers under test that support touch events also support the HTML5 htmlFor attribute
505 if (labelElement.htmlFor) {
506 return document.getElementById(labelElement.htmlFor);
509 // If no for attribute exists, attempt to retrieve the first labellable descendant element
510 // the list of which is defined here: http://www.w3.org/TR/html5/forms.html#category-label
511 return labelElement.querySelector('button, input:not([type=hidden]), keygen, meter, output, progress, select, textarea');
516 * On touch end, determine whether to send a click event at once.
518 * @param {Event} event
521 FastClick.prototype.onTouchEnd = function(event) {
522 var forElement, trackingClickStart, targetTagName, scrollParent, touch, targetElement = this.targetElement;
524 if (!this.trackingClick) {
528 // Prevent phantom clicks on fast double-tap (issue #36)
529 if ((event.timeStamp - this.lastClickTime) < this.tapDelay) {
530 this.cancelNextClick = true;
534 if ((event.timeStamp - this.trackingClickStart) > this.tapTimeout) {
538 // Reset to prevent wrong click cancel on input (issue #156).
539 this.cancelNextClick = false;
541 this.lastClickTime = event.timeStamp;
543 trackingClickStart = this.trackingClickStart;
544 this.trackingClick = false;
545 this.trackingClickStart = 0;
547 // On some iOS devices, the targetElement supplied with the event is invalid if the layer
548 // is performing a transition or scroll, and has to be re-detected manually. Note that
549 // for this to function correctly, it must be called *after* the event target is checked!
550 // See issue #57; also filed as rdar://13048589 .
551 if (deviceIsIOSWithBadTarget) {
552 touch = event.changedTouches[0];
554 // In certain cases arguments of elementFromPoint can be negative, so prevent setting targetElement to null
555 targetElement = document.elementFromPoint(touch.pageX - window.pageXOffset, touch.pageY - window.pageYOffset) || targetElement;
556 targetElement.fastClickScrollParent = this.targetElement.fastClickScrollParent;
559 targetTagName = targetElement.tagName.toLowerCase();
560 if (targetTagName === 'label') {
561 forElement = this.findControl(targetElement);
563 this.focus(targetElement);
564 if (deviceIsAndroid) {
568 targetElement = forElement;
570 } else if (this.needsFocus(targetElement)) {
572 // Case 1: If the touch started a while ago (best guess is 100ms based on tests for issue #36) then focus will be triggered anyway. Return early and unset the target element reference so that the subsequent click will be allowed through.
573 // Case 2: Without this exception for input elements tapped when the document is contained in an iframe, then any inputted text won't be visible even though the value attribute is updated as the user types (issue #37).
574 if ((event.timeStamp - trackingClickStart) > 100 || (deviceIsIOS && window.top !== window && targetTagName === 'input')) {
575 this.targetElement = null;
579 this.focus(targetElement);
580 this.sendClick(targetElement, event);
582 // Select elements need the event to go through on iOS 4, otherwise the selector menu won't open.
583 // Also this breaks opening selects when VoiceOver is active on iOS6, iOS7 (and possibly others)
584 if (!deviceIsIOS || targetTagName !== 'select') {
585 this.targetElement = null;
586 event.preventDefault();
592 if (deviceIsIOS && !deviceIsIOS4) {
594 // Don't send a synthetic click event if the target element is contained within a parent layer that was scrolled
595 // and this tap is being used to stop the scrolling (usually initiated by a fling - issue #42).
596 scrollParent = targetElement.fastClickScrollParent;
597 if (scrollParent && scrollParent.fastClickLastScrollTop !== scrollParent.scrollTop) {
602 // Prevent the actual click from going though - unless the target node is marked as requiring
603 // real clicks or if it is in the whitelist in which case only non-programmatic clicks are permitted.
604 if (!this.needsClick(targetElement)) {
605 event.preventDefault();
606 this.sendClick(targetElement, event);
614 * On touch cancel, stop tracking the click.
618 FastClick.prototype.onTouchCancel = function() {
619 this.trackingClick = false;
620 this.targetElement = null;
625 * Determine mouse events which should be permitted.
627 * @param {Event} event
630 FastClick.prototype.onMouse = function(event) {
632 // If a target element was never set (because a touch event was never fired) allow the event
633 if (!this.targetElement) {
637 if (event.forwardedTouchEvent) {
641 // Programmatically generated events targeting a specific element should be permitted
642 if (!event.cancelable) {
646 // Derive and check the target element to see whether the mouse event needs to be permitted;
647 // unless explicitly enabled, prevent non-touch click events from triggering actions,
648 // to prevent ghost/doubleclicks.
649 if (!this.needsClick(this.targetElement) || this.cancelNextClick) {
651 // Prevent any user-added listeners declared on FastClick element from being fired.
652 if (event.stopImmediatePropagation) {
653 event.stopImmediatePropagation();
656 // Part of the hack for browsers that don't support Event#stopImmediatePropagation (e.g. Android 2)
657 event.propagationStopped = true;
661 event.stopPropagation();
662 event.preventDefault();
667 // If the mouse event is permitted, return true for the action to go through.
673 * On actual clicks, determine whether this is a touch-generated click, a click action occurring
674 * naturally after a delay after a touch (which needs to be cancelled to avoid duplication), or
675 * an actual click which should be permitted.
677 * @param {Event} event
680 FastClick.prototype.onClick = function(event) {
683 // It's possible for another FastClick-like library delivered with third-party code to fire a click event before FastClick does (issue #44). In that case, set the click-tracking flag back to false and return early. This will cause onTouchEnd to return early.
684 if (this.trackingClick) {
685 this.targetElement = null;
686 this.trackingClick = false;
690 // Very odd behaviour on iOS (issue #18): if a submit element is present inside a form and the user hits enter in the iOS simulator or clicks the Go button on the pop-up OS keyboard the a kind of 'fake' click event will be triggered with the submit-type input element as the target.
691 if (event.target.type === 'submit' && event.detail === 0) {
695 permitted = this.onMouse(event);
697 // Only unset targetElement if the click is not permitted. This will ensure that the check for !targetElement in onMouse fails and the browser's click doesn't go through.
699 this.targetElement = null;
702 // If clicks are permitted, return true for the action to go through.
708 * Remove all FastClick's event listeners.
712 FastClick.prototype.destroy = function() {
713 var layer = this.layer;
715 if (deviceIsAndroid) {
716 layer.removeEventListener('mouseover', this.onMouse, true);
717 layer.removeEventListener('mousedown', this.onMouse, true);
718 layer.removeEventListener('mouseup', this.onMouse, true);
721 layer.removeEventListener('click', this.onClick, true);
722 layer.removeEventListener('touchstart', this.onTouchStart, false);
723 layer.removeEventListener('touchmove', this.onTouchMove, false);
724 layer.removeEventListener('touchend', this.onTouchEnd, false);
725 layer.removeEventListener('touchcancel', this.onTouchCancel, false);
730 * Check whether FastClick is needed.
732 * @param {Element} layer The layer to listen on
734 FastClick.notNeeded = function(layer) {
737 var blackberryVersion;
740 // Devices that don't support touch don't need FastClick
741 if (typeof window.ontouchstart === 'undefined') {
745 // Chrome version - zero for other browsers
746 chromeVersion = +(/Chrome\/([0-9]+)/.exec(navigator.userAgent) || [,0])[1];
750 if (deviceIsAndroid) {
751 metaViewport = document.querySelector('meta[name=viewport]');
754 // Chrome on Android with user-scalable="no" doesn't need FastClick (issue #89)
755 if (metaViewport.content.indexOf('user-scalable=no') !== -1) {
758 // Chrome 32 and above with width=device-width or less don't need FastClick
759 if (chromeVersion > 31 && document.documentElement.scrollWidth <= window.outerWidth) {
764 // Chrome desktop doesn't need FastClick (issue #15)
770 if (deviceIsBlackBerry10) {
771 blackberryVersion = navigator.userAgent.match(/Version\/([0-9]*)\.([0-9]*)/);
773 // BlackBerry 10.3+ does not require Fastclick library.
774 // https://github.com/ftlabs/fastclick/issues/251
775 if (blackberryVersion[1] >= 10 && blackberryVersion[2] >= 3) {
776 metaViewport = document.querySelector('meta[name=viewport]');
779 // user-scalable=no eliminates click delay.
780 if (metaViewport.content.indexOf('user-scalable=no') !== -1) {
783 // width=device-width (or less than device-width) eliminates click delay.
784 if (document.documentElement.scrollWidth <= window.outerWidth) {
791 // IE10 with -ms-touch-action: none or manipulation, which disables double-tap-to-zoom (issue #97)
792 if (layer.style.msTouchAction === 'none' || layer.style.touchAction === 'manipulation') {
796 // Firefox version - zero for other browsers
797 firefoxVersion = +(/Firefox\/([0-9]+)/.exec(navigator.userAgent) || [,0])[1];
799 if (firefoxVersion >= 27) {
800 // Firefox 27+ does not have tap delay if the content is not zoomable - https://bugzilla.mozilla.org/show_bug.cgi?id=922896
802 metaViewport = document.querySelector('meta[name=viewport]');
803 if (metaViewport && (metaViewport.content.indexOf('user-scalable=no') !== -1 || document.documentElement.scrollWidth <= window.outerWidth)) {
808 // IE11: prefixed -ms-touch-action is no longer supported and it's recomended to use non-prefixed version
809 // http://msdn.microsoft.com/en-us/library/windows/apps/Hh767313.aspx
810 if (layer.style.touchAction === 'none' || layer.style.touchAction === 'manipulation') {
819 * Factory method for creating a FastClick object
821 * @param {Element} layer The layer to listen on
822 * @param {Object} [options={}] The options to override the defaults
824 FastClick.attach = function(layer, options) {
825 return new FastClick(layer, options);
829 if (typeof define === 'function' && typeof define.amd === 'object' && define.amd) {
831 // AMD. Register as an anonymous module.
835 } else if (typeof module !== 'undefined' && module.exports) {
836 module.exports = FastClick.attach;
837 module.exports.FastClick = FastClick;
839 window.FastClick = FastClick;