0
# Browser APIs
1

2
Comprehensive browser API wrappers for clipboard, geolocation, permissions, notifications, and device capabilities with reactive state management.
3

4
## Capabilities
5

6
### Clipboard
7

8
#### useClipboard
9

10
Reactive clipboard API with read/write permissions handling.
11

12
```typescript { .api }
13
/**
14
 * Reactive clipboard API with permission handling
15
 * @param options - Configuration options
16
 * @returns Clipboard utilities
17
 */
18
function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
19

20
interface UseClipboardReturn {
21
  isSupported: ComputedRef<boolean>;
22
  text: ComputedRef<string>;
23
  copied: ComputedRef<boolean>;
24
  copy: (text?: string) => Promise<void>;
25
}
26

27
interface UseClipboardOptions extends ConfigurableNavigator {
28
  read?: boolean;
29
  source?: MaybeRefOrGetter<string>;
30
  copiedDuring?: number;
31
}
32
```
33

34
#### useClipboardItems
35

36
Advanced clipboard API for multiple data types and formats.
37

38
```typescript { .api }
39
/**
40
 * Advanced clipboard API for multiple data types
41
 * @param options - Configuration options
42
 * @returns Advanced clipboard utilities
43
 */
44
function useClipboardItems(options?: UseClipboardItemsOptions): UseClipboardItemsReturn;
45

46
interface UseClipboardItemsReturn {
47
  isSupported: ComputedRef<boolean>;
48
  content: ComputedRef<ClipboardItems>;
49
  copy: (content: ClipboardItems) => Promise<void>;
50
}
51
```
52

53
### Geolocation
54

55
#### useGeolocation
56

57
Reactive geolocation API with position tracking.
58

59
```typescript { .api }
60
/**
61
 * Reactive geolocation API with position tracking
62
 * @param options - Geolocation options
63
 * @returns Geolocation state and utilities
64
 */
65
function useGeolocation(options?: UseGeolocationOptions): UseGeolocationReturn;
66

67
interface UseGeolocationReturn {
68
  coords: Ref<GeolocationCoordinates>;
69
  locatedAt: Ref<number | null>;
70
  error: ShallowRef<GeolocationPositionError | null>;
71
  resume: Fn;
72
  pause: Fn;
73
}
74

75
interface UseGeolocationOptions extends Pausable, ConfigurableNavigator {
76
  enableHighAccuracy?: boolean;
77
  maximumAge?: number;
78
  timeout?: number;
79
  immediate?: boolean;
80
}
81
```
82

83
### Permissions
84

85
#### usePermission
86

87
Reactive permissions API for checking and requesting permissions.
88

89
```typescript { .api }
90
/**
91
 * Reactive permissions API
92
 * @param permissionDesc - Permission descriptor
93
 * @param options - Configuration options
94
 * @returns Permission state
95
 */
96
function usePermission(
97
  permissionDesc: PermissionDescriptor | PermissionDescriptor['name'],
98
  options?: UsePermissionOptions
99
): UsePermissionReturn;
100

101
interface UsePermissionReturn {
102
  state: Ref<PermissionState | undefined>;
103
  isSupported: Ref<boolean>;
104
  query: () => Promise<PermissionStatus | undefined>;
105
}
106
```
107

108
### Notifications
109

110
#### useWebNotification
111

112
Reactive Web Notifications API with permission management.
113

114
```typescript { .api }
115
/**
116
 * Reactive Web Notifications API
117
 * @param title - Notification title
118
 * @param options - Configuration options
119
 * @returns Notification utilities
120
 */
121
function useWebNotification(
122
  title?: MaybeRefOrGetter<string>,
123
  options?: UseWebNotificationOptions
124
): UseWebNotificationReturn;
125

126
interface UseWebNotificationReturn {
127
  isSupported: ComputedRef<boolean>;
128
  notification: Ref<Notification | null>;
129
  show: (overrides?: UseWebNotificationOptions) => Promise<Notification | undefined>;
130
  close: () => void;
131
  onClick: EventHookOn<Event>;
132
  onShow: EventHookOn<Event>;
133
  onError: EventHookOn<Event>;
134
  onClose: EventHookOn<Event>;
135
}
136
```
137

138
### File System
139

140
#### useFileDialog
141

142
Programmatically open file dialog with reactive file handling.
143

144
```typescript { .api }
145
/**
146
 * Programmatically open file dialog
147
 * @param options - File dialog options
148
 * @returns File dialog utilities
149
 */
150
function useFileDialog(options?: UseFileDialogOptions): UseFileDialogReturn;
151

152
interface UseFileDialogReturn {
153
  files: Ref<FileList | null>;
154
  open: (localOptions?: Partial<UseFileDialogOptions>) => void;
155
  reset: () => void;
156
  onChange: EventHookOn<Event>;
157
}
158

159
interface UseFileDialogOptions {
160
  multiple?: boolean;
161
  accept?: string;
162
  capture?: string;
163
  reset?: boolean;
164
}
165
```
166

167
#### useFileSystemAccess
168

169
Reactive File System Access API for reading and writing files.
170

171
```typescript { .api }
172
/**
173
 * Reactive File System Access API
174
 * @param options - Configuration options
175
 * @returns File system access utilities
176
 */
177
function useFileSystemAccess(options?: UseFileSystemAccessOptions): UseFileSystemAccessReturn;
178

179
interface UseFileSystemAccessReturn {
180
  isSupported: ComputedRef<boolean>;
181
  data: Ref<string | ArrayBuffer | null>;
182
  file: Ref<File | null>;
183
  fileName: Ref<string>;
184
  fileMIME: Ref<string>;
185
  fileSize: Ref<number>;
186
  fileLastModified: Ref<number>;
187
  open: (options?: OpenFilePickerOptions) => Promise<void>;
188
  create: (options?: SaveFilePickerOptions) => Promise<void>;
189
  save: (options?: SaveFilePickerOptions) => Promise<void>;
190
  saveAs: (options?: SaveFilePickerOptions) => Promise<void>;
191
  updateData: () => Promise<void>;
192
}
193
```
194

195
### Media & Device APIs
196

197
#### useEyeDropper
198

199
Reactive EyeDropper API for color picking.
200

201
```typescript { .api }
202
/**
203
 * Reactive EyeDropper API for color picking
204
 * @param options - Configuration options
205
 * @returns EyeDropper utilities
206
 */
207
function useEyeDropper(options?: UseEyeDropperOptions): UseEyeDropperReturn;
208

209
interface UseEyeDropperReturn {
210
  isSupported: ComputedRef<boolean>;
211
  sRGBHex: Ref<string>;
212
  open: (openOptions?: EyeDropperOpenOptions) => Promise<{ sRGBHex: string } | undefined>;
213
}
214
```
215

216
#### useVibrate
217

218
Reactive Vibration API for haptic feedback.
219

220
```typescript { .api }
221
/**
222
 * Reactive Vibration API for haptic feedback
223
 * @param options - Configuration options
224
 * @returns Vibration utilities
225
 */
226
function useVibrate(options?: UseVibrateOptions): UseVibrateReturn;
227

228
interface UseVibrateReturn {
229
  isSupported: ComputedRef<boolean>;
230
  isvibrating: Ref<boolean>;
231
  pattern: Ref<VibratePattern>;
232
  intervalControls: Pausable;
233
  vibrate: (pattern?: VibratePattern) => void;
234
  stop: () => void;
235
}
236

237
type VibratePattern = number | number[];
238
```
239

240
### Wake Lock
241

242
#### useWakeLock
243

244
Reactive Screen Wake Lock API to prevent screen from sleeping.
245

246
```typescript { .api }
247
/**
248
 * Reactive Screen Wake Lock API
249
 * @param options - Configuration options
250
 * @returns Wake lock utilities
251
 */
252
function useWakeLock(options?: UseWakeLockOptions): UseWakeLockReturn;
253

254
interface UseWakeLockReturn {
255
  isSupported: ComputedRef<boolean>;
256
  wakeLock: Ref<WakeLockSentinel | null>;
257
  request: (type?: WakeLockType) => Promise<void>;
258
  release: () => Promise<void>;
259
}
260
```
261

262
### Share API
263

264
#### useShare
265

266
Reactive Web Share API for sharing content.
267

268
```typescript { .api }
269
/**
270
 * Reactive Web Share API
271
 * @param shareOptions - Default share options
272
 * @param options - Configuration options
273
 * @returns Share utilities
274
 */
275
function useShare(
276
  shareOptions?: MaybeRefOrGetter<ShareData>,
277
  options?: UseShareOptions
278
): UseShareReturn;
279

280
interface UseShareReturn {
281
  share: (overrideOptions?: MaybeRefOrGetter<ShareData>) => Promise<void>;
282
  isSupported: ComputedRef<boolean>;
283
}
284
```
285

286
### Document APIs
287

288
#### useTitle
289

290
Reactive document title management.
291

292
```typescript { .api }
293
/**
294
 * Reactive document title management
295
 * @param newTitle - New title (reactive)
296
 * @param options - Configuration options
297
 * @returns Reactive title ref
298
 */
299
function useTitle(
300
  newTitle?: MaybeRefOrGetter<string | null | undefined>,
301
  options?: UseTitleOptions
302
): ComputedRef<string | null | undefined>;
303

304
interface UseTitleOptions extends ConfigurableDocument {
305
  titleTemplate?: MaybeRefOrGetter<string> | ((title: string) => string);
306
  observe?: boolean;
307
  restoreOnUnmount?: boolean;
308
}
309
```
310

311
#### useFavicon
312

313
Reactive favicon management.
314

315
```typescript { .api }
316
/**
317
 * Reactive favicon management
318
 * @param newIcon - New favicon URL (reactive)
319
 * @param options - Configuration options
320
 * @returns Reactive favicon ref
321
 */
322
function useFavicon(
323
  newIcon?: MaybeRefOrGetter<string | null | undefined>,
324
  options?: UseFaviconOptions
325
): ComputedRef<string | null | undefined>;
326

327
interface UseFaviconOptions extends ConfigurableDocument {
328
  baseUrl?: string;
329
  rel?: string;
330
}
331
```
332

333
#### useDocumentVisibility
334

335
Reactive document visibility state tracking.
336

337
```typescript { .api }
338
/**
339
 * Reactive document visibility state
340
 * @param options - Configuration options
341
 * @returns Reactive visibility state
342
 */
343
function useDocumentVisibility(options?: ConfigurableDocument): Ref<DocumentVisibilityState>;
344
```
345

346
#### usePageLeave
347

348
Reactive page leave detection for handling beforeunload events.
349

350
```typescript { .api }
351
/**
352
 * Reactive page leave detection
353
 * @param options - Configuration options
354
 * @returns Reactive page leave state
355
 */
356
function usePageLeave(options?: ConfigurableWindow): Ref<boolean>;
357
```
358

359
### Browser Location
360

361
#### useBrowserLocation
362

363
Reactive browser location information.
364

365
```typescript { .api }
366
/**
367
 * Reactive browser location information
368
 * @param options - Configuration options
369
 * @returns Reactive location state
370
 */
371
function useBrowserLocation(options?: UseBrowserLocationOptions): UseBrowserLocationReturn;
372

373
interface UseBrowserLocationReturn {
374
  trigger: () => void;
375
  coords: Ref<GeolocationCoordinates>;
376
  locatedAt: Ref<number | null>;
377
  error: ShallowRef<GeolocationPositionError | null>;
378
  resume: Fn;
379
  pause: Fn;
380
}
381
```
382

383
#### useNavigatorLanguage
384

385
Reactive navigator language tracking.
386

387
```typescript { .api }
388
/**
389
 * Reactive navigator language
390
 * @param options - Configuration options
391
 * @returns Reactive language state
392
 */
393
function useNavigatorLanguage(options?: ConfigurableNavigator): UseNavigatorLanguageReturn;
394

395
interface UseNavigatorLanguageReturn {
396
  isSupported: Ref<boolean>;
397
  language: ComputedRef<string>;
398
  languages: ComputedRef<readonly string[]>;
399
}
400
```
401

402
### Theme & Color Mode
403

404
#### useColorMode
405

406
Reactive color mode (light/dark/auto) with automatic persistence and DOM integration.
407

408
```typescript { .api }
409
/**
410
 * Reactive color mode with automatic persistence
411
 * @param options - Color mode configuration options
412
 * @returns Reactive color mode state
413
 */
414
function useColorMode<T extends string = BasicColorMode>(
415
  options?: UseColorModeOptions<T>
416
): Ref<T | BasicColorMode>;
417

418
interface UseColorModeOptions<T extends string = BasicColorMode> {
419
  selector?: string | MaybeElementRef;
420
  attribute?: string;
421
  initialValue?: MaybeRefOrGetter<T | BasicColorSchema>;
422
  modes?: Partial<Record<T | BasicColorSchema, string>>;
423
  onChanged?: (mode: T | BasicColorMode, defaultHandler: (mode: T | BasicColorMode) => void) => void;
424
  storageKey?: string;
425
  storage?: StorageLike;
426
  storageRef?: Ref<T | BasicColorMode>;
427
  emitAuto?: boolean;
428
  disableTransition?: boolean;
429
}
430

431
type BasicColorMode = 'light' | 'dark';
432
type BasicColorSchema = BasicColorMode | 'auto';
433
```
434

435
#### useDark
436

437
Reactive dark mode toggle with auto data persistence.
438

439
```typescript { .api }
440
/**
441
 * Reactive dark mode with auto data persistence
442
 * @param options - Dark mode configuration options
443
 * @returns Reactive dark mode state
444
 */
445
function useDark(options?: UseDarkOptions): WritableComputedRef<boolean>;
446

447
interface UseDarkOptions extends Omit<UseColorModeOptions<BasicColorSchema>, 'modes' | 'onChanged'> {
448
  valueDark?: string;
449
  valueLight?: string;
450
  onChanged?: (isDark: boolean, defaultHandler: (mode: BasicColorSchema) => void, mode: BasicColorSchema) => void;
451
}
452
```
453

454
### Media & Display
455

456
#### useFullscreen
457

458
Reactive fullscreen API for elements.
459

460
```typescript { .api }
461
/**
462
 * Reactive fullscreen API
463
 * @param target - Target element for fullscreen
464
 * @param options - Fullscreen configuration options
465
 * @returns Fullscreen state and controls
466
 */
467
function useFullscreen(
468
  target?: MaybeElementRef,
469
  options?: UseFullscreenOptions
470
): UseFullscreenReturn;
471

472
interface UseFullscreenReturn {
473
  isSupported: ComputedRef<boolean>;
474
  isFullscreen: Ref<boolean>;
475
  enter: () => Promise<void>;
476
  exit: () => Promise<void>;
477
  toggle: () => Promise<void>;
478
}
479

480
interface UseFullscreenOptions extends ConfigurableDocument {
481
  autoExit?: boolean;
482
}
483
```
484

485
#### useUserMedia
486

487
Reactive access to user media devices (camera/microphone).
488

489
```typescript { .api }
490
/**
491
 * Reactive user media access
492
 * @param options - Media constraints and configuration
493
 * @returns Media stream state and controls
494
 */
495
function useUserMedia(
496
  options?: UseUserMediaOptions
497
): UseUserMediaReturn;
498

499
interface UseUserMediaReturn {
500
  isSupported: ComputedRef<boolean>;
501
  stream: Ref<MediaStream | undefined>;
502
  start: () => Promise<MediaStream | undefined>;
503
  stop: () => void;
504
  restart: () => Promise<MediaStream | undefined>;
505
  videoInputs: ComputedRef<MediaDeviceInfo[]>;
506
  audioInputs: ComputedRef<MediaDeviceInfo[]>;
507
  audioOutputs: ComputedRef<MediaDeviceInfo[]>;
508
}
509

510
interface UseUserMediaOptions extends ConfigurableNavigator {
511
  enabled?: MaybeRef<boolean>;
512
  autoSwitch?: MaybeRef<boolean>;
513
  constraints?: MaybeRef<MediaStreamConstraints>;
514
}
515
```
516

517
#### useDisplayMedia
518

519
Reactive screen sharing via getDisplayMedia API.
520

521
```typescript { .api }
522
/**
523
 * Reactive screen sharing access
524
 * @param options - Display media configuration options
525
 * @returns Display media stream state and controls
526
 */
527
function useDisplayMedia(
528
  options?: UseDisplayMediaOptions
529
): UseDisplayMediaReturn;
530

531
interface UseDisplayMediaReturn {
532
  isSupported: ComputedRef<boolean>;
533
  stream: Ref<MediaStream | undefined>;
534
  start: () => Promise<MediaStream | undefined>;
535
  stop: () => void;
536
}
537

538
interface UseDisplayMediaOptions {
539
  enabled?: MaybeRef<boolean>;
540
  video?: boolean | MediaTrackConstraints;
541
  audio?: boolean | MediaTrackConstraints;
542
}
543
```