0
# Browser APIs
1

2
Integration with browser APIs including clipboard, media queries, fullscreen, viewport, scroll, color scheme detection, and document management.
3

4
## Capabilities
5

6
### useClipboard
7

8
Clipboard API integration with copy status tracking and error handling.
9

10
```typescript { .api }
11
/**
12
 * Clipboard API integration with status tracking
13
 * @param options - Configuration for timeout
14
 * @returns Object with copy function, status, and error
15
 */
16
function useClipboard(options?: UseClipboardOptions): UseClipboardReturnValue;
17

18
interface UseClipboardOptions {
19
  timeout?: number; // Duration to show "copied" state (default: 2000ms)
20
}
21

22
interface UseClipboardReturnValue {
23
  copy: (value: any) => void;
24
  reset: () => void;
25
  error: Error | null;
26
  copied: boolean;
27
}
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
import { useClipboard } from "@mantine/hooks";
34

35
function CopyButton({ text }: { text: string }) {
36
  const clipboard = useClipboard({ timeout: 2000 });
37
  
38
  return (
39
    <button
40
      onClick={() => clipboard.copy(text)}
41
      style={{ color: clipboard.copied ? 'green' : 'black' }}
42
    >
43
      {clipboard.copied ? 'Copied!' : 'Copy'}
44
    </button>
45
  );
46
}
47

48
// Copy complex data
49
function ShareButton({ data }: { data: object }) {
50
  const clipboard = useClipboard();
51
  
52
  const handleShare = () => {
53
    clipboard.copy(JSON.stringify(data, null, 2));
54
  };
55
  
56
  if (clipboard.error) {
57
    return <div>Failed to copy: {clipboard.error.message}</div>;
58
  }
59
  
60
  return <button onClick={handleShare}>Share Data</button>;
61
}
62
```
63

64
### useColorScheme
65

66
Detect system color scheme preference (dark/light mode).
67

68
```typescript { .api }
69
/**
70
 * Detect system color scheme preference
71
 * @param defaultValue - Fallback value if detection fails
72
 * @returns Current color scheme ('dark' or 'light')
73
 */
74
function useColorScheme(defaultValue?: UseColorSchemeValue): UseColorSchemeValue;
75

76
type UseColorSchemeValue = 'dark' | 'light';
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
import { useColorScheme } from "@mantine/hooks";
83

84
function ThemedComponent() {
85
  const colorScheme = useColorScheme('light');
86
  
87
  return (
88
    <div style={{
89
      background: colorScheme === 'dark' ? '#000' : '#fff',
90
      color: colorScheme === 'dark' ? '#fff' : '#000'
91
    }}>
92
      Current theme: {colorScheme}
93
    </div>
94
  );
95
}
96
```
97

98
### useMediaQuery
99

100
React to CSS media query changes with SSR support.
101

102
```typescript { .api }
103
/**
104
 * React to CSS media query changes
105
 * @param query - CSS media query string
106
 * @param initialValue - Initial value for SSR
107
 * @param options - Configuration for effect timing
108
 * @returns Boolean indicating if media query matches
109
 */
110
function useMediaQuery(
111
  query: string,
112
  initialValue?: boolean,
113
  options?: UseMediaQueryOptions
114
): boolean;
115

116
interface UseMediaQueryOptions {
117
  getInitialValueInEffect: boolean; // Prevent SSR hydration issues
118
}
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
import { useMediaQuery } from "@mantine/hooks";
125

126
function ResponsiveComponent() {
127
  const isMobile = useMediaQuery('(max-width: 768px)');
128
  const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
129
  const isLandscape = useMediaQuery('(orientation: landscape)');
130
  
131
  return (
132
    <div>
133
      <p>Mobile: {isMobile ? 'Yes' : 'No'}</p>
134
      <p>Dark mode: {isDarkMode ? 'Yes' : 'No'}</p>
135
      <p>Landscape: {isLandscape ? 'Yes' : 'No'}</p>
136
    </div>
137
  );
138
}
139

140
// SSR-safe usage
141
function SSRComponent() {
142
  const isLargeScreen = useMediaQuery('(min-width: 1200px)', false, {
143
    getInitialValueInEffect: true
144
  });
145
  
146
  return isLargeScreen ? <DesktopLayout /> : <MobileLayout />;
147
}
148
```
149

150
### useViewportSize
151

152
Track viewport dimensions with automatic updates on resize.
153

154
```typescript { .api }
155
/**
156
 * Track viewport dimensions
157
 * @returns Object with current height and width
158
 */
159
function useViewportSize(): { height: number; width: number };
160
```
161

162
**Usage Examples:**
163

164
```typescript
165
import { useViewportSize } from "@mantine/hooks";
166

167
function ViewportInfo() {
168
  const { height, width } = useViewportSize();
169
  
170
  return (
171
    <div>
172
      Viewport: {width} × {height}
173
      {width < 768 && <MobileWarning />}
174
    </div>
175
  );
176
}
177
```
178

179
### useWindowScroll
180

181
Track and control window scroll position.
182

183
```typescript { .api }
184
/**
185
 * Track and control window scroll position
186
 * @returns Object with scroll position and scroll control function
187
 */
188
function useWindowScroll(): UseWindowScrollReturnValue;
189

190
interface UseWindowScrollPosition {
191
  x: number;
192
  y: number;
193
}
194

195
interface UseWindowScrollTo {
196
  (options: ScrollToOptions): void;
197
  (x: number, y: number): void;
198
}
199

200
interface UseWindowScrollReturnValue {
201
  x: number;
202
  y: number;
203
  scrollTo: UseWindowScrollTo;
204
}
205
```
206

207
**Usage Examples:**
208

209
```typescript
210
import { useWindowScroll } from "@mantine/hooks";
211

212
function ScrollInfo() {
213
  const { x, y, scrollTo } = useWindowScroll();
214
  
215
  return (
216
    <div>
217
      <p>Scroll position: {x}, {y}</p>
218
      <button onClick={() => scrollTo({ top: 0, behavior: 'smooth' })}>
219
        Scroll to top
220
      </button>
221
      <button onClick={() => scrollTo(0, 500)}>
222
        Scroll to 500px
223
      </button>
224
    </div>
225
  );
226
}
227
```
228

229
### useFullscreen
230

231
Fullscreen API integration with element control.
232

233
```typescript { .api }
234
/**
235
 * Fullscreen API integration
236
 * @returns Object with ref, fullscreen controls, and state
237
 */
238
function useFullscreen<T extends HTMLElement = any>(): UseFullscreenReturnValue<T>;
239

240
interface UseFullscreenReturnValue<T extends HTMLElement = any> {
241
  ref: React.RefCallback<T | null>;
242
  toggle: () => Promise<void>;
243
  enter: () => Promise<void>;
244
  exit: () => Promise<void>;
245
  fullscreen: boolean;
246
}
247
```
248

249
**Usage Examples:**
250

251
```typescript
252
import { useFullscreen } from "@mantine/hooks";
253

254
function VideoPlayer() {
255
  const { ref, toggle, fullscreen } = useFullscreen();
256
  
257
  return (
258
    <div ref={ref}>
259
      <video src="/video.mp4" />
260
      <button onClick={toggle}>
261
        {fullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'}
262
      </button>
263
    </div>
264
  );
265
}
266
```
267

268
### useDocumentTitle
269

270
Manage document title with automatic cleanup.
271

272
```typescript { .api }
273
/**
274
 * Manage document title
275
 * @param title - Title to set
276
 */
277
function useDocumentTitle(title: string): void;
278
```
279

280
**Usage Examples:**
281

282
```typescript
283
import { useDocumentTitle } from "@mantine/hooks";
284

285
function ProductPage({ product }: { product: Product }) {
286
  useDocumentTitle(`${product.name} - My Store`);
287
  
288
  return <div>{product.name}</div>;
289
}
290
```
291

292
### useDocumentVisibility
293

294
Track document visibility state (tab active/inactive).
295

296
```typescript { .api }
297
/**
298
 * Track document visibility state
299
 * @returns Current visibility state
300
 */
301
function useDocumentVisibility(): DocumentVisibilityState;
302
```
303

304
**Usage Examples:**
305

306
```typescript
307
import { useDocumentVisibility } from "@mantine/hooks";
308

309
function VideoPlayer() {
310
  const documentState = useDocumentVisibility();
311
  
312
  // Pause video when tab is not visible
313
  useEffect(() => {
314
    if (documentState === 'hidden') {
315
      pauseVideo();
316
    } else {
317
      resumeVideo();
318
    }
319
  }, [documentState]);
320
  
321
  return <video />;
322
}
323
```
324

325
### useFavicon
326

327
Dynamically change favicon.
328

329
```typescript { .api }
330
/**
331
 * Dynamically change favicon
332
 * @param url - URL of the favicon
333
 */
334
function useFavicon(url: string): void;
335
```
336

337
### usePageLeave
338

339
Detect when user leaves page (mouse leaves viewport).
340

341
```typescript { .api }
342
/**
343
 * Detect when user leaves page
344
 * @param fn - Function to call when user leaves
345
 */
346
function usePageLeave(fn: () => void): void;
347
```
348

349
### useHash
350

351
Manage URL hash with getter and setter.
352

353
```typescript { .api }
354
/**
355
 * Manage URL hash
356
 * @param options - Configuration for effect timing
357
 * @returns Object with current hash and setter
358
 */
359
function useHash(options?: UseHashOptions): UseHashReturnValue;
360

361
interface UseHashOptions {
362
  getInitialValueInEffect?: boolean;
363
}
364

365
interface UseHashReturnValue {
366
  hash: string;
367
  setHash: (value: string) => void;
368
}
369
```
370

371
**Usage Examples:**
372

373
```typescript
374
import { useHash } from "@mantine/hooks";
375

376
function TabsWithHash() {
377
  const { hash, setHash } = useHash();
378
  const activeTab = hash.replace('#', '') || 'overview';
379
  
380
  return (
381
    <div>
382
      <button 
383
        onClick={() => setHash('overview')}
384
        className={activeTab === 'overview' ? 'active' : ''}
385
      >
386
        Overview
387
      </button>
388
      <button 
389
        onClick={() => setHash('details')}
390
        className={activeTab === 'details' ? 'active' : ''}
391
      >
392
        Details
393
      </button>
394
      
395
      {activeTab === 'overview' && <OverviewTab />}
396
      {activeTab === 'details' && <DetailsTab />}
397
    </div>
398
  );
399
}
400
```