0
# Mobile Detect
1

2
Mobile Detect is a JavaScript library that provides comprehensive device detection capabilities by analyzing User-Agent strings. It identifies mobile devices, tablets, phones, operating systems, browsers, and specific device versions for both client-side and server-side environments.
3

4
## Package Information
5

6
- **Package Name**: mobile-detect
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mobile-detect`
10

11
## Core Imports
12

13
```javascript
14
const MobileDetect = require('mobile-detect');
15
```
16

17
For ES6 modules:
18

19
```javascript
20
import MobileDetect from 'mobile-detect';
21
```
22

23
For browser usage:
24

25
```html
26
<script src="mobile-detect.js"></script>
27
<!-- Available as window.MobileDetect -->
28
```
29

30
## Basic Usage
31

32
```javascript
33
const MobileDetect = require('mobile-detect');
34

35
// Create instance with User-Agent string
36
const md = new MobileDetect(
37
  'Mozilla/5.0 (Linux; U; Android 4.0.3; en-in; SonyEricssonMT11i Build/4.1.A.0.562) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30'
38
);
39

40
// Detect device types
41
console.log(md.mobile());     // 'Sony'
42
console.log(md.phone());      // 'Sony' 
43
console.log(md.tablet());     // null
44

45
// Detect system information
46
console.log(md.os());         // 'AndroidOS'
47
console.log(md.userAgent());  // 'Safari'
48

49
// Test device characteristics  
50
console.log(md.is('iPhone')); // false
51
console.log(md.is('android')); // true
52

53
// Get version information
54
console.log(md.version('Webkit')); // 534.3
55
console.log(md.mobileGrade());      // 'A'
56
```
57

58
## Architecture
59

60
Mobile Detect operates through several key components:
61

62
- **Constructor Pattern**: Create instances with User-Agent strings for analysis
63
- **Device Detection**: Identify specific device manufacturers and models using pattern matching
64
- **System Analysis**: Extract operating system, browser, and version information
65
- **Classification**: Categorize devices as mobile/tablet/phone with capability grading
66
- **Pattern Matching**: Internal regex-based detection rules for comprehensive device support
67
- **Caching**: Internal result caching for performance optimization
68

69
## Capabilities
70

71
### Device Type Detection
72

73
Core device identification functionality for determining if a device is mobile, phone, or tablet, along with manufacturer detection.
74

75
```javascript { .api }
76
class MobileDetect {
77
  constructor(userAgent: string, maxPhoneWidth?: number);
78
  
79
  mobile(): string | null;
80
  phone(): string | null;  
81
  tablet(): string | null;
82
}
83
```
84

85
[Device Detection](./device-detection.md)
86

87
### System Information Detection
88

89
Extract detailed information about operating systems, browsers, and User-Agent characteristics from device strings.
90

91
```javascript { .api }
92
class MobileDetect {
93
  userAgent(): string | null;
94
  userAgents(): string[];
95
  os(): string | null;
96
}
97
```
98

99
[System Information](./system-information.md)
100

101
### Version and Testing Utilities  
102

103
Advanced functionality for version extraction, device testing, and pattern matching against User-Agent strings.
104

105
```javascript { .api }
106
class MobileDetect {
107
  version(key: string): number;
108
  versionStr(key: string): string | null;
109
  is(key: string): boolean;
110
  match(pattern: string | RegExp): boolean;
111
  isPhoneSized(maxPhoneWidth?: number): boolean | undefined;
112
  mobileGrade(): string;
113
}
114

115
// Static methods
116
MobileDetect.version: string;
117
MobileDetect.isPhoneSized(maxPhoneWidth?: number): boolean | undefined;
118
```
119

120
[Version and Testing](./version-testing.md)
121

122
## Types
123

124
```javascript { .api }
125
/**
126
 * MobileDetect constructor
127
 * @param userAgent - The User-Agent string to analyze (required)
128
 * @param maxPhoneWidth - Optional maximum width in pixels to consider as phone-sized
129
 *                        (default: 600). Only used for isPhoneSized() method in browser environments.
130
 *                        Has no effect in server-side environments.
131
 */
132
class MobileDetect {
133
  constructor(userAgent: string, maxPhoneWidth?: number);
134
}
135

136
/**
137
 * Rule definition interfaces for type safety
138
 */
139
interface MobileDetectRules {
140
  [key: string]: string | RegExp;
141
}
142

143
interface MobileDetectComplexRules {
144
  [key: string]: string | RegExp | string[] | RegExp[];
145
}
146

147
/**
148
 * Internal implementation interface (for extensibility and monkey-patching only)
149
 * Warning: These methods are internal and may change between versions
150
 */
151
interface MobileDetectImpl {
152
  mobileDetectRules: {
153
    phones: MobileDetectRules;
154
    tablets: MobileDetectRules;
155
    oss: MobileDetectRules;
156
    uas: MobileDetectRules;
157
    props: MobileDetectComplexRules;
158
    utils: MobileDetectRules;
159
  };
160
  detectMobileBrowsers: {
161
    fullPattern: RegExp;
162
    shortPattern: RegExp;
163
    tabletPattern: RegExp;
164
  };
165
  FALLBACK_PHONE: string;
166
  FALLBACK_TABLET: string;
167
  FALLBACK_MOBILE: string;
168
  
169
  // Internal methods (not recommended for public use)
170
  findMatch(rules: MobileDetectRules, userAgent: string): string;
171
  findMatches(rules: MobileDetectRules, userAgent: string): string[];
172
  getVersionStr(propertyName: string, userAgent: string): string;
173
  getVersion(propertyName: string, userAgent: string): number;
174
  prepareVersionNo(version: string): number;
175
  isMobileFallback(userAgent: string): boolean;
176
  isTabletFallback(userAgent: string): boolean;
177
  prepareDetectionCache(cache: Object, userAgent: string, maxPhoneWidth?: number): void;
178
  mobileGrade(md: MobileDetect): string;
179
  detectOS(userAgent: string): string;
180
  getDeviceSmallerSide(): number;
181
}
182
```
183

184
## Important Notes
185

186
- **Reliability Warning**: User-Agent based detection is inherently unreliable due to constantly changing patterns and spoofing
187
- **Alternatives Recommended**: Feature detection (Modernizr) and media queries are preferred for most use cases
188
- **Environment Support**: Works in browsers, Node.js, and other JavaScript environments
189
- **Pattern Updates**: Detection patterns require continuous updates as new devices are released
190
- **Performance**: Internal caching optimizes repeated method calls on the same instance