0
# Device & Sensors
1

2
Device motion, orientation, battery status, and viewport utilities for responsive and context-aware applications.
3

4
## Capabilities
5

6
### Device Motion & Orientation
7

8
#### useDeviceMotion
9

10
Reactive device motion sensor data from accelerometer and gyroscope.
11

12
```typescript { .api }
13
/**
14
 * Reactive device motion sensor data
15
 * @param options - Configuration options
16
 * @returns Device motion state
17
 */
18
function useDeviceMotion(options?: UseDeviceMotionOptions): UseDeviceMotionReturn;
19

20
interface UseDeviceMotionReturn {
21
  acceleration: Ref<DeviceMotionEventAcceleration | null>;
22
  accelerationIncludingGravity: Ref<DeviceMotionEventAcceleration | null>;
23
  rotationRate: Ref<DeviceMotionEventRotationRate | null>;
24
  interval: Ref<number>;
25
}
26

27
interface UseDeviceMotionOptions extends ConfigurableWindow, ConfigurableEventFilter {
28
  immediate?: boolean;
29
}
30
```
31

32
#### useDeviceOrientation
33

34
Reactive device orientation sensor for detecting device rotation.
35

36
```typescript { .api }
37
/**
38
 * Reactive device orientation sensor
39
 * @param options - Configuration options
40
 * @returns Device orientation state
41
 */
42
function useDeviceOrientation(options?: UseDeviceOrientationOptions): UseDeviceOrientationReturn;
43

44
interface UseDeviceOrientationReturn {
45
  isAbsolute: Ref<boolean>;
46
  alpha: Ref<number | null>;
47
  beta: Ref<number | null>;
48
  gamma: Ref<number | null>;
49
}
50

51
interface UseDeviceOrientationOptions extends ConfigurableWindow, ConfigurableEventFilter {
52
  immediate?: boolean;
53
}
54
```
55

56
#### useScreenOrientation
57

58
Reactive screen orientation API for detecting and controlling screen rotation.
59

60
```typescript { .api }
61
/**
62
 * Reactive screen orientation API
63
 * @param options - Configuration options
64
 * @returns Screen orientation state and controls
65
 */
66
function useScreenOrientation(options?: UseScreenOrientationOptions): UseScreenOrientationReturn;
67

68
interface UseScreenOrientationReturn {
69
  isSupported: ComputedRef<boolean>;
70
  orientation: Ref<ScreenOrientation | undefined>;
71
  angle: ComputedRef<number>;
72
  type: ComputedRef<OrientationType>;
73
  lockOrientation: (type: OrientationLockType) => Promise<void>;
74
  unlockOrientation: () => void;
75
}
76
```
77

78
### Battery Status
79

80
#### useBattery
81

82
Reactive battery status API for monitoring device power.
83

84
```typescript { .api }
85
/**
86
 * Reactive battery status API
87
 * @param options - Configuration options
88
 * @returns Battery status state
89
 */
90
function useBattery(options?: UseBatteryOptions): UseBatteryReturn;
91

92
interface UseBatteryReturn {
93
  isSupported: Ref<boolean>;
94
  charging: Ref<boolean>;
95
  chargingTime: Ref<number>;
96
  dischargingTime: Ref<number>;
97
  level: Ref<number>;
98
}
99

100
interface UseBatteryOptions extends ConfigurableNavigator, ConfigurableEventFilter {
101
  immediate?: boolean;
102
}
103
```
104

105
### Memory Information
106

107
#### useMemory
108

109
Reactive device memory information from performance API.
110

111
```typescript { .api }
112
/**
113
 * Reactive device memory information
114
 * @param options - Configuration options
115
 * @returns Memory information state
116
 */
117
function useMemory(options?: UseMemoryOptions): UseMemoryReturn;
118

119
interface UseMemoryReturn {
120
  isSupported: Ref<boolean>;
121
  deviceMemory?: Ref<number>;
122
  totalJSHeapSize?: Ref<number>;
123
  usedJSHeapSize?: Ref<number>;
124
  jsHeapSizeLimit?: Ref<number>;
125
}
126
```
127

128
### Network Status
129

130
#### useNetwork
131

132
Reactive network connection status and type detection.
133

134
```typescript { .api }
135
/**
136
 * Reactive network connection status
137
 * @param options - Configuration options
138
 * @returns Network status state
139
 */
140
function useNetwork(options?: UseNetworkOptions): UseNetworkReturn;
141

142
interface UseNetworkReturn {
143
  isSupported: Ref<boolean>;
144
  isOnline: Ref<boolean>;
145
  saveData: Ref<boolean | undefined>;
146
  offlineAt: Ref<number | undefined>;
147
  onlineAt: Ref<number | undefined>;
148
  downlink: Ref<number | undefined>;
149
  downlinkMax: Ref<number | undefined>;
150
  rtt: Ref<number | undefined>;
151
  effectiveType: Ref<string | undefined>;
152
  type: Ref<string>;
153
}
154

155
interface UseNetworkOptions extends ConfigurableWindow, ConfigurableEventFilter {
156
  immediate?: boolean;
157
}
158
```
159

160
#### useOnline
161

162
Simple reactive online/offline status detection.
163

164
```typescript { .api }
165
/**
166
 * Simple reactive online/offline status
167
 * @param options - Configuration options
168
 * @returns Online status state
169
 */
170
function useOnline(options?: ConfigurableWindow): Ref<boolean>;
171
```
172

173
### Viewport & Breakpoints
174

175
#### useBreakpoints
176

177
Reactive viewport breakpoints with shortcut methods.
178

179
```typescript { .api }
180
/**
181
 * Reactive viewport breakpoints with shortcuts
182
 * @param breakpoints - Breakpoint definitions
183
 * @param options - Configuration options
184
 * @returns Breakpoint utilities
185
 */
186
function useBreakpoints<K extends string>(
187
  breakpoints: Record<K, number | string>,
188
  options?: UseBreakpointsOptions
189
): UseBreakpointsReturn<K>;
190

191
interface UseBreakpointsReturn<K extends string> {
192
  greater: (k: K) => ComputedRef<boolean>;
193
  greaterOrEqual: (k: K) => ComputedRef<boolean>;
194
  smaller: (k: K) => ComputedRef<boolean>;
195
  smallerOrEqual: (k: K) => ComputedRef<boolean>;
196
  between: (a: K, b: K) => ComputedRef<boolean>;
197
  isGreater: (k: K) => boolean;
198
  isGreaterOrEqual: (k: K) => boolean;
199
  isSmaller: (k: K) => boolean;
200
  isSmallerOrEqual: (k: K) => boolean;
201
  isInBetween: (a: K, b: K) => boolean;
202
  current: () => ComputedRef<K[]>;
203
  active: () => ComputedRef<K>;
204
}
205

206
interface UseBreakpointsOptions extends ConfigurableWindow {
207
  strategy?: 'min-width' | 'max-width';
208
}
209
```
210

211
**Usage Examples:**
212

213
```typescript
214
import { useBreakpoints } from "@vueuse/core";
215

216
// Define breakpoints
217
const breakpoints = useBreakpoints({
218
  tablet: 768,
219
  laptop: 1024,
220
  desktop: 1280,
221
});
222

223
// Use breakpoint utilities
224
const laptop = breakpoints.greater('tablet'); // tablet < screen
225
const desktop = breakpoints.between('laptop', 'desktop'); // laptop <= screen < desktop
226

227
// Current active breakpoint
228
const current = breakpoints.current(); // ['tablet', 'laptop']
229
const active = breakpoints.active(); // 'laptop'
230
```
231

232
#### useMediaQuery
233

234
Reactive media query matching for responsive design.
235

236
```typescript { .api }
237
/**
238
 * Reactive media query matching
239
 * @param query - Media query string
240
 * @param options - Configuration options
241
 * @returns Reactive media query match state
242
 */
243
function useMediaQuery(
244
  query: MaybeRefOrGetter<string>,
245
  options?: UseMediaQueryOptions
246
): Ref<boolean>;
247

248
interface UseMediaQueryOptions extends ConfigurableWindow {
249
  immediate?: boolean;
250
}
251
```
252

253
#### useDevicePixelRatio
254

255
Reactive device pixel ratio tracking for high-DPI displays.
256

257
```typescript { .api }
258
/**
259
 * Reactive device pixel ratio
260
 * @param options - Configuration options
261
 * @returns Reactive pixel ratio state
262
 */
263
function useDevicePixelRatio(options?: UseDevicePixelRatioOptions): UseDevicePixelRatioReturn;
264

265
interface UseDevicePixelRatioReturn {
266
  pixelRatio: Ref<number>;
267
}
268
```
269

270
#### useScreenSafeArea
271

272
Reactive screen safe area insets for handling notches and rounded corners.
273

274
```typescript { .api }
275
/**
276
 * Reactive screen safe area insets
277
 * @returns Safe area inset values
278
 */
279
function useScreenSafeArea(): {
280
  top: Ref<string>;
281
  right: Ref<string>;
282
  bottom: Ref<string>;
283
  left: Ref<string>;
284
  update: () => void;
285
};
286
```
287

288
### Device Lists
289

290
#### useDevicesList
291

292
List available input/output devices (cameras, microphones, speakers).
293

294
```typescript { .api }
295
/**
296
 * List available input/output devices
297
 * @param options - Configuration options
298
 * @returns Device list state and utilities
299
 */
300
function useDevicesList(options?: UseDevicesListOptions): UseDevicesListReturn;
301

302
interface UseDevicesListReturn {
303
  devices: Ref<MediaDeviceInfo[]>;
304
  videoInputs: ComputedRef<MediaDeviceInfo[]>;
305
  audioInputs: ComputedRef<MediaDeviceInfo[]>;
306
  audioOutputs: ComputedRef<MediaDeviceInfo[]>;
307
  isSupported: Ref<boolean>;
308
  permissionGranted: Ref<boolean>;
309
  ensurePermissions: () => Promise<boolean>;
310
  update: () => Promise<void>;
311
}
312

313
interface UseDevicesListOptions extends ConfigurableNavigator {
314
  onUpdated?: (devices: MediaDeviceInfo[]) => void;
315
  immediate?: boolean;
316
  constraints?: MediaStreamConstraints;
317
}
318
```
319

320
### Window & Viewport Properties
321

322
#### useWindowSize
323

324
Reactive window size tracking with customizable inclusion of scrollbars.
325

326
```typescript { .api }
327
/**
328
 * Reactive window size
329
 * @param options - Configuration options
330
 * @returns Reactive window dimensions
331
 */
332
function useWindowSize(options?: UseWindowSizeOptions): {
333
  width: Ref<number>;
334
  height: Ref<number>;
335
};
336

337
interface UseWindowSizeOptions extends ConfigurableWindow {
338
  initialWidth?: number;
339
  initialHeight?: number;
340
  listenOrientation?: boolean;
341
  includeScrollbar?: boolean;
342
}
343
```
344

345
#### useWindowFocus
346

347
Reactive window focus state tracking.
348

349
```typescript { .api }
350
/**
351
 * Reactive window focus state
352
 * @param options - Configuration options
353
 * @returns Reactive focus state
354
 */
355
function useWindowFocus(options?: ConfigurableWindow): Ref<boolean>;
356
```
357

358
### Idle Detection
359

360
#### useIdle
361

362
Reactive idle state detection based on user activity.
363

364
```typescript { .api }
365
/**
366
 * Reactive idle state detection
367
 * @param timeout - Idle timeout in milliseconds
368
 * @param options - Configuration options
369
 * @returns Idle state and utilities
370
 */
371
function useIdle(
372
  timeout?: number,
373
  options?: UseIdleOptions
374
): UseIdleReturn;
375

376
interface UseIdleReturn {
377
  idle: Ref<boolean>;
378
  lastActive: Ref<number>;
379
  reset: () => void;
380
}
381

382
interface UseIdleOptions extends ConfigurableWindow, ConfigurableEventFilter {
383
  events?: UseIdleEvents[];
384
  listenForVisibilityChange?: boolean;
385
  initialState?: boolean;
386
}
387

388
type UseIdleEvents = 'mousemove' | 'mousedown' | 'resize' | 'keydown' | 'touchstart' | 'wheel';
389
```
390

391
### Gamepad Support
392

393
#### useGamepad
394

395
Reactive Gamepad API for controller input handling.
396

397
```typescript { .api }
398
/**
399
 * Reactive Gamepad API for controller input
400
 * @param options - Configuration options
401
 * @returns Gamepad state and utilities
402
 */
403
function useGamepad(options?: UseGamepadOptions): UseGamepadReturn;
404

405
interface UseGamepadReturn {
406
  isSupported: Ref<boolean>;
407
  gamepads: Ref<(Gamepad | null)[]>;
408
  start: () => void;
409
  stop: () => void;
410
  pause: () => void;
411
  resume: () => void;
412
  mapGamepad: (gamepad: Gamepad) => Record<string, any>;
413
}
414
```