detect-it

What is detect-it?

The detect-it npm package is designed to help developers detect various input methods and device capabilities. It can identify whether a device supports touch, mouse, or stylus inputs, and can also determine if the device is a mobile or desktop device.

What are detect-it's main functionalities?

Detecting Touch Support

This feature allows you to check if the device supports touch input. The `hasTouch` property will return `true` if touch is supported and `false` otherwise.

const detectIt = require('detect-it');
console.log(detectIt.hasTouch); // true or false

Detecting Mouse Support

This feature allows you to check if the device supports mouse input. The `hasMouse` property will return `true` if a mouse is supported and `false` otherwise.

const detectIt = require('detect-it');
console.log(detectIt.hasMouse); // true or false

Detecting Primary Input Method

This feature allows you to determine the primary input method of the device. The `primaryInput` property will return either 'mouse', 'touch', or 'stylus' based on the primary input method detected.

const detectIt = require('detect-it');
console.log(detectIt.primaryInput); // 'mouse', 'touch', or 'stylus'

Detecting Device Type

This feature allows you to determine the type of device. The `deviceType` property will return 'mouseOnly', 'touchOnly', 'hybrid', or 'unknown' based on the detected input methods.

const detectIt = require('detect-it');
console.log(detectIt.deviceType); // 'mouseOnly', 'touchOnly', 'hybrid', or 'unknown'

Other packages similar to detect-it

detect-touch

The detect-touch package is a lightweight library that focuses on detecting touch capabilities of a device. It is simpler and more focused compared to detect-it, which offers a broader range of input detection features.

bowser

Bowser is a browser detection library that can identify the browser, its version, and the operating system. While it does not specifically focus on input methods like detect-it, it provides comprehensive information about the user's environment.

mobile-detect

Mobile-detect is a user-agent parser that can detect mobile devices, tablets, and their operating systems. It offers broader device detection capabilities compared to detect-it, which is more focused on input methods.

README

Detect It

Detect if a device is mouse only, touch only, or hybrid, and if it supports passive event listeners.

Live detection test

Exports a reference to a singleton object (a micro state machine with an update function) with its state set to if the device is mouse only, touch only, or hybrid (and other related info about the device), as well as an update() function which updates the object's state.

detect-it's state is a deterministic function of the state of the four micro state machines that it contains (detect-hover, detect-pointer, detect-touch-events, and detect-passive-events). detect-it's update() function first runs the update() function on each micro state machine that it contains, and then updates it own state.

Note that Detect It v2 removed support for Pointer Events detection because they're just not relevant enough (only used by IE and Edge and not supported by React). If you need Pointer Events detection, use Detect It v1.1.

detectIt micro state machine

const detectIt = {
  deviceType: 'mouseOnly' / 'touchOnly' / 'hybrid',
  passiveEvents: boolean,
  hasMouse: boolean,
  hasTouch: boolean,
  maxTouchPoints: whole number,
  primaryHover: 'hover' / 'none',
  primaryPointer: 'fine' / 'coarse' / 'none',

  // access to the four micro state machines that it contains
  state: {
    detectHover,
    detectPointer,
    detectTouchEvents,
    detectPassiveEvents,
  },

  // updates the state of the four micro state machines it contains, and then updates its own state
  update() {...},
}

Installing detect-it

$ npm install --save detect-it

Using detect-it

import detectIt from 'detect-it';

// using the state
detectIt.deviceType === 'mouseOnly' / 'touchOnly' / 'hybrid'; // the device type

detectIt.passiveEvents === true; // the browser supports passive event listeners

detectIt.hasMouse === true; // the deviceType is mouseOnly or hybrid

// the browser supports the touch events api, and the deviceType is touchOnly or hybrid
detectIt.hasTouch === true;

detectIt.maxTouchPoints; // max number of touch points supported

detectIt.primaryHover === 'hover' / 'none'; // can the primary pointing system easily hover
detectIt.primaryPointer === 'fine' / `coarse` / 'none'; // how accurate is the primary pointing system


// accessing the state of the micro state machines that detectIt contains
detectIt.state.detectHover; // see the detect-hover repo for more info
detectIt.state.detectPointer; // see the detect-pointer repo for more info
detectIt.state.detectTouchEvents; // see the detect-touch-events repo for more info
detectIt.state.detectPassiveEvents; // see the detect-passive-events repo for more info


// updating the state - most apps won't need to use this at all
detectIt.update();

/*
 * note that in the case of a legacy computer and browser, one that
 * doesn't support any of detect-it's detection tests, the default state will be:
 */
const detectIt = {
  deviceType: 'mouseOnly',
  passiveEvents: false,
  hasMouse: true,
  hasTouch: false,
  maxTouchPoints: undefined,
  primaryHover: 'hover',
  primaryPointer: 'fine',
}

/*
 * note that in the case of a legacy touch device, one that supports the touch events api,
 * but not any of the other detection tests, the default state will be:
 */
const detectIt = {
  deviceType: 'touchOnly',
  passiveEvents: false,
  hasMouse: false,
  hasTouch: true,
  maxTouchPoints: undefined,
  primaryHover: 'none',
  primaryPointer: 'coarse',
}

Note that the update() function is run once at the time of import to set the object's initial state, and generally doesn't need to be run again. If it doesn't have access to the window, then the state will be undefined (detect-it will not throw an error), and you will have to call the update() function manually at a later time to update its state.

Using detect-it to set event listeners

// if passive events are supported by the browser
if (detectIt.passiveEvents === true) {
  document.addEventListener('scroll', handleScroll, { capture: false, passive: true });
} else {
  document.addEventListener('scroll', handleScroll, false);
}

if (detectIt.hasMouse) {
  // set mouse event listeners
}
if (detectIt.hasTouch) {
  // set touch event listeners
}

// OR

if (detectIt.deviceType === 'mouseOnly') {
  // only set mouse event listeners
}
if (detectIt.deviceType === 'touchOnly') {
  // only set touch event listeners
}
if (detectIt.deviceType === 'hybrid') {
  // set both mouse and touch event listeners
}

Using detect-it to adjust the user interface

if (detectIt.primaryPointer === 'coarse') {
  // make clickable elements bigger
}

if (detectIt.primaryHover === 'hover') {
  // can add hover features
}

Real world example using detect-it

• react-interactive - a better interactive state machine than CSS

Part of the detect-it family

• detect-it
  • detect-hover
  • detect-pointer
  • detect-touch-events
  • detect-passive-events

For more information

• hover and any-hover media queries see the W3C Media Queries Level 4 specification, hover section
• pointer and any-pointer media queries see the W3C Media Queries Level 4 specification, pointer section
• Touch events api see MDN's Touch Events, or the W3C Touch Events specification
• General playground see the excellent suite of touch/pointer tests and demos put together by Patrick H. Lauke
• Passive events see this Passive Events Explainer

Notes about detecting the deviceType

I chose a wide definition for what constitutes a hybrid device, or rather a strict definition for what are mouseOnly and touchOnly devices, because if a device strays from a fine point and hover with a mouse, or a coarse touch with a finger, then it should be treated uniquely when considering how the user will interact with it, and so is placed in the broad hybrid category.

// this is the function used by detect-it to determine the device type
function determineDeviceType(hasTouch, anyHover, anyFine) {
  /*
   * A hybrid device is one that both hasTouch and any input device can hover
   * or has a fine pointer.
   */
  if (hasTouch && (anyHover || anyFine)) return 'hybrid';

  /*
   * In almost all cases a device that doesn’t support touch will have a mouse,
   * but there may be rare exceptions. Note that it doesn’t work to do additional tests
   * based on hover and pointer media queries as older browsers don’t support these.
   * Essentially, 'mouseOnly' is the default.
   */
  return hasTouch ? 'touchOnly' : 'mouseOnly';
}

Some hybrid examples:

• A touch capable Chromebook with Chrome browser registers that hasTouch, anyHover, and anyFine are all true.
• The Galaxy Note with stylus running the Chrome mobile browser registers that hasTouch and anyFine are true, but that anyHover is false - as a side note I think that since the stylus hovers effectively, the Note should register as anyHover true, but for some reason it doesn't.
• The Microsoft Surface (and other Windows 10 touchscreen computers)
  • When using the Chrome browser, hasTouch, anyHover and anyFine are all true because Chrome supports the Touch Events API, so the device registers as a hybrid.
  • When using Microsoft's Edge browser hasTouch is false because Edge doesn't support the Touch Events API, so it registers as a mouseOnly device. To access the touch capabilities in Edge you have to use Pointer Events. If you want Edge to register as a hybrid device then use Detect It v1.1 which supports Pointer Events. Note that touches will still fire mouse events, so if you don't set Pointer Event listeners, touch input will act like a mouse.