mobile-detect.js - Documentation

Introduction

What is mobile-detect.js?

mobile-detect.js is a lightweight JavaScript library designed to detect devices (desktops, tablets, and phones) and their operating systems. It parses the user agent string provided by the browser to identify the device type and version information. This allows developers to tailor their web applications or websites based on the user’s device capabilities. It avoids reliance on CSS media queries alone, offering a programmatic way to access device information.

Why use mobile-detect.js?

Installation and Setup

The simplest way to include mobile-detect.js is via a <script> tag in your HTML file. You can download the library from [Insert download link here] and place it in your project. Then, include it in your HTML like this:

<script src="mobile-detect.js"></script>

Alternatively, you can use a package manager like npm or yarn if your project uses one:

# npm
npm install mobile-detect

# yarn
yarn add mobile-detect

After installation (via either method), you’ll need to require or import the library depending on your module system (e.g., ES modules, CommonJS):

// ES Modules
import MobileDetect from 'mobile-detect';

// CommonJS
const MobileDetect = require('mobile-detect');

Basic Usage Example

This example demonstrates how to create a MobileDetect object and use its methods to detect various device properties:

const md = new MobileDetect(window.navigator.userAgent);

// Check if it's a mobile device
if (md.isMobile()) {
  console.log('This is a mobile device!');
}

// Get the operating system
const os = md.os();
console.log('Operating System:', os);

// Get the device type
const device = md.device();
console.log('Device Type:', device);

// Check for specific devices or OS versions
if (md.is('iPhone')) {
  console.log('This is an iPhone!');
}

if (md.version('Android') >= 8) {
  console.log('Android version 8 or higher');
}


// Get a comprehensive report
console.log('Full device info:', md.userAgent()); // For debugging

Remember to replace "mobile-detect.js" with the actual path to the library file if you downloaded it manually. This basic example shows how to initialize the library and check for different device characteristics. The complete API documentation provides a more exhaustive list of methods and their functionalities.

Core Functionality

Detecting Mobile Devices

mobile-detect.js offers several methods to detect mobile devices. The primary method is isMobile(), which returns true if the user agent indicates a mobile device and false otherwise. More specific detection is possible using methods like is('iPhone'), is('iPad'), is('Android'), etc. These methods check for specific device models or brands. Remember that user agent strings can be manipulated, so this detection is based on the information provided by the browser.

Detecting Operating Systems

The library provides methods to identify the operating system. os() returns a string representing the detected operating system (e.g., “Android”, “iOS”, “Windows Phone”). You can also check for specific OS versions using version('Android') or similar methods. These return a version number as a string (e.g., “8.1”, “16”), or null if the OS is not detected or the version information is unavailable.

Detecting Browsers

While primarily focused on device detection, mobile-detect.js can also infer the browser being used through the user agent string. However, this is a secondary feature; more robust browser detection might require a dedicated library if that’s a primary need for your project. You can indirectly infer information about the browser by analyzing other properties (like the OS) and comparing them to common browser-OS pairings.

Detecting Features (e.g., Touch)

mobile-detect.js doesn’t directly detect features like touch input, but infers the likelihood of touch capabilities based on the detected device type. For example, if isMobile() returns true and the device is identified as a smartphone or tablet, it’s highly probable that the device supports touch input. However, this is an indirect inference, and you should use browser feature detection (e.g., 'ontouchstart' in window) for accurate and reliable feature detection.

Using the mobileDetect Object

The core of the library revolves around the MobileDetect object. You create an instance by passing the user agent string to the constructor:

const md = new MobileDetect(window.navigator.userAgent);

Once you have a md object, you can call its various methods to access information:

Each method returns the detected information or null if the information is unavailable or not applicable. Always check for null values before using the returned data to prevent errors in your application.

Advanced Usage

Customizing Detection Rules

While mobile-detect.js provides a comprehensive set of default detection rules, you might need to customize them for specific scenarios. This is not directly supported through a configuration API within the library itself. The detection logic is embedded within the library’s core. To customize, you’d need to fork the library and modify its internal regular expressions and conditional logic directly; then, rebuild and use your customized version. This approach requires a good understanding of the library’s source code and regular expression syntax. Consider the maintenance implications if you choose this route.

Handling Specific Devices or OS Versions

The library provides methods to handle specific devices and OS versions. Use is('deviceName') to check for specific devices (e.g., md.is('iPhone')), and version('osName') to get the version of a particular OS (e.g., md.version('Android')). You can combine these methods to create conditional logic for your application based on specific devices and OS versions. For instance:

if (md.is('iPhone') && parseFloat(md.version('iOS')) >= 15) {
  // Code for iPhones running iOS 15 or higher
}

Remember that version numbers are returned as strings; you might need to parse them using parseFloat() for numerical comparisons.

Integration with Frameworks (e.g., React, Angular)

Integrating mobile-detect.js with frameworks like React or Angular is straightforward. For React, you can use it within functional components or class components:

import React, { useState, useEffect } from 'react';
import MobileDetect from 'mobile-detect';

function MyComponent() {
  const [isMobile, setIsMobile] = useState(false);

  useEffect(() => {
    const md = new MobileDetect(window.navigator.userAgent);
    setIsMobile(md.isMobile());
  }, []);

  return (
    <div>
      {isMobile ? <p>Mobile device detected</p> : <p>Not a mobile device</p>}
    </div>
  );
}

For Angular, you can inject it into a service or component similarly, depending on your application’s architecture. The core principle remains the same: instantiate MobileDetect and access its methods to determine the device information within the context of your framework’s lifecycle methods (e.g., ngOnInit in Angular, useEffect in React).

Asynchronous Detection

mobile-detect.js is synchronous; it performs detection immediately when the MobileDetect object is created. No asynchronous operations are involved. If you need to perform detection within an asynchronous context (e.g., after fetching data from an API), you can simply call the detection methods within your asynchronous callback or promise.

Error Handling and Fallbacks

The library’s methods generally return null if no information is available. Always check for null values before using the returned data. Consider providing fallback mechanisms in your application’s logic to gracefully handle cases where device information cannot be reliably determined:

const os = md.os() || 'Unknown OS'; // Provides a fallback if OS detection fails

This approach prevents errors and ensures your application handles unexpected situations robustly. You may also add overall error handling using try-catch blocks if necessary, though the library itself generally doesn’t throw errors.

API Reference

mobileDetect.version(osName)

This method returns the version number of a specified operating system. The osName argument is a string representing the operating system (e.g., “Android”, “iOS”). The method returns a string representing the version number if detected, otherwise null. Note that the version number is a string and might need to be parsed (e.g., using parseFloat()) for numerical comparisons.

const md = new MobileDetect(navigator.userAgent);
const androidVersion = md.version('Android'); // Returns a string like "12", "13", null, etc.
console.log("Android Version:", androidVersion);

mobileDetect.phone()

Returns a string indicating the detected phone model or brand if available; otherwise, it returns null. The detection relies on patterns within the user agent string and might not be perfectly accurate in all cases.

const md = new MobileDetect(navigator.userAgent);
const phone = md.phone(); // Returns a string like "iPhone", "Samsung Galaxy S23", null, etc.
console.log("Phone:", phone);

mobileDetect.tablet()

Similar to mobileDetect.phone(), this method returns a string representing the detected tablet model or brand if available, and null otherwise.

const md = new MobileDetect(navigator.userAgent);
const tablet = md.tablet(); // Returns a string like "iPad", "Samsung Galaxy Tab S8", null, etc.
console.log("Tablet:", tablet);

mobileDetect.os()

Returns a string representing the detected operating system (e.g., “Android”, “iOS”, “Windows Phone”, etc.). Returns null if no operating system can be reliably identified.

const md = new MobileDetect(navigator.userAgent);
const operatingSystem = md.os(); // Returns a string like "Android", "iOS", "Windows", null, etc.
console.log("Operating System:", operatingSystem);

mobileDetect.browser()

Returns a string representing the detected browser (e.g., “Chrome”, “Firefox”, “Safari”). Keep in mind that browser detection in this library is less emphasized than OS and device detection. Returns null if the browser cannot be confidently identified.

const md = new MobileDetect(navigator.userAgent);
const browser = md.browser(); // Returns a string like "Chrome", "Firefox", "Safari", null, etc.
console.log("Browser:", browser);

All other detection methods

Beyond the methods listed above, mobile-detect.js provides a range of other detection methods, generally following the pattern is(string) where string represents the device or feature to check. Examples include isMobile(), isTablet(), is('iPhone'), is('iPad'), is('Android'), and many others. These methods return a boolean value (true or false) indicating whether the specified device or feature is detected. Consult the full list available in the library documentation for a complete reference.

Utility methods

The primary utility method is userAgent(), which returns the original user agent string passed to the MobileDetect constructor. This is helpful for debugging and understanding the source data used for device detection. There are no other significant “utility” methods beyond this core functionality.

const md = new MobileDetect(navigator.userAgent);
console.log("User Agent:", md.userAgent());

Troubleshooting

Common Issues and Solutions

Debugging Tips

Frequently Asked Questions (FAQs)

Support and Community Resources

For support, you can check the project’s GitHub repository for issues and discussions. You might also find answers to your questions in the documentation or online forums. Please follow the project’s contribution guidelines if you wish to report bugs or suggest enhancements.

Contributing

Contributing Code

We welcome contributions to mobile-detect.js! If you’d like to contribute code, please follow these steps:

  1. Fork the Repository: Fork the official mobile-detect.js repository on GitHub.

  2. Create a Branch: Create a new branch for your feature or bug fix. Use descriptive branch names (e.g., fix-iphone-detection, feature-new-device-support).

  3. Make Your Changes: Implement your changes, ensuring they adhere to the code style guide (see below). Thoroughly test your changes to prevent regressions.

  4. Commit Your Changes: Commit your changes with clear and concise commit messages explaining the purpose of each change.

  5. Push Your Branch: Push your branch to your forked repository on GitHub.

  6. Create a Pull Request: Create a pull request from your branch to the main branch of the official repository. Provide a detailed description of your changes and address any comments from the reviewers.

Reporting Bugs

When reporting bugs, please provide the following information:

Suggesting Enhancements

If you have suggestions for enhancements, please create an issue on the GitHub repository. Include a clear description of the enhancement, its purpose, and potential benefits. Consider providing examples or mockups to illustrate your ideas. The more details you provide, the easier it will be for the maintainers to evaluate your suggestion.

Code Style Guide

The mobile-detect.js project follows a consistent code style. Please adhere to these guidelines when contributing code:

Before submitting a pull request, please ensure your code passes the linting and testing process. The project likely uses a linter (e.g., ESLint); follow the instructions in the project’s documentation to setup and run the linter locally.

License

License Information

mobile-detect.js is typically licensed under the [Insert License Name Here, e.g., MIT License]. You can find the complete license text in the LICENSE file within the project’s root directory. This license grants you certain permissions to use, modify, and distribute the library. Please carefully review the license terms before using the library in your projects.

Terms of Use

By using mobile-detect.js, you agree to abide by the terms and conditions specified in the license. This generally includes, but is not limited to:

Always refer to the complete license text (LICENSE) for the definitive terms of use. If you have any questions or concerns about the license, please contact the project maintainers.