0
# Screenfull
1

2
Screenfull is a simple wrapper for cross-browser usage of the JavaScript Fullscreen API, which lets you bring the page or any element into fullscreen. It smoothens out the browser implementation differences across WebKit, Mozilla, and Microsoft prefixed APIs, providing a unified interface for fullscreen functionality.
3

4
## Package Information
5

6
- **Package Name**: screenfull
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Module)
9
- **Installation**: `npm install screenfull`
10

11
## Core Imports
12

13
```javascript
14
import screenfull from 'screenfull';
15
```
16

17
For environments requiring CommonJS (versions prior to 6.x):
18

19
```javascript
20
const screenfull = require('screenfull');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import screenfull from 'screenfull';
27

28
// Check if fullscreen is supported
29
if (screenfull.isEnabled) {
30
  // Make the entire page fullscreen
31
  document.getElementById('button').addEventListener('click', () => {
32
    screenfull.request();
33
  });
34
  
35
  // Listen for fullscreen changes
36
  screenfull.on('change', () => {
37
    console.log('Am I fullscreen?', screenfull.isFullscreen ? 'Yes' : 'No');
38
  });
39
  
40
  // Handle fullscreen errors
41
  screenfull.on('error', event => {
42
    console.error('Failed to enable fullscreen', event);
43
  });
44
}
45
```
46

47
## Architecture
48

49
Screenfull provides:
50

51
- **Cross-browser compatibility**: Handles vendor prefixes automatically (webkit, moz, ms)
52
- **Promise-based API**: All fullscreen operations return promises for async handling
53
- **Event system**: Standard event listening for fullscreen state changes and errors
54
- **Element targeting**: Support for making specific elements fullscreen, not just the page
55
- **Graceful degradation**: Provides `isEnabled` check for unsupported environments
56

57
## Capabilities
58

59
### Fullscreen Request
60

61
Request fullscreen mode for an element or the entire page.
62

63
```javascript { .api }
64
/**
65
 * Make an element fullscreen
66
 * @param element - Element to make fullscreen (defaults to document.documentElement)
67
 * @param options - FullscreenOptions for configuration
68
 * @returns Promise that resolves when element enters fullscreen
69
 */
70
request(element?: Element, options?: FullscreenOptions): Promise<void>;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
import screenfull from 'screenfull';
77

78
// Fullscreen the entire page
79
if (screenfull.isEnabled) {
80
  await screenfull.request();
81
}
82

83
// Fullscreen a specific element
84
const videoElement = document.getElementById('video');
85
if (screenfull.isEnabled) {
86
  await screenfull.request(videoElement);
87
}
88

89
// Fullscreen with options (hide navigation UI on mobile)
90
const targetElement = document.getElementById('game');
91
if (screenfull.isEnabled) {
92
  await screenfull.request(targetElement, { navigationUI: 'hide' });
93
}
94
```
95

96
### Exit Fullscreen
97

98
Exit fullscreen mode.
99

100
```javascript { .api }
101
/**
102
 * Brings you out of fullscreen
103
 * @returns Promise that resolves after exiting fullscreen
104
 */
105
exit(): Promise<void>;
106
```
107

108
**Usage Example:**
109

110
```javascript
111
import screenfull from 'screenfull';
112

113
if (screenfull.isFullscreen) {
114
  await screenfull.exit();
115
}
116
```
117

118
### Toggle Fullscreen
119

120
Toggle fullscreen state - enter if not active, exit if active.
121

122
```javascript { .api }
123
/**
124
 * Requests fullscreen if not active, otherwise exits
125
 * @param element - Element to make fullscreen (defaults to document.documentElement)
126
 * @param options - FullscreenOptions for configuration
127
 * @returns Promise that resolves after entering/exiting fullscreen
128
 */
129
toggle(element?: Element, options?: FullscreenOptions): Promise<void>;
130
```
131

132
**Usage Example:**
133

134
```javascript
135
import screenfull from 'screenfull';
136

137
// Toggle fullscreen on image click
138
document.querySelectorAll('img').forEach(img => {
139
  img.addEventListener('click', () => {
140
    if (screenfull.isEnabled) {
141
      screenfull.toggle(img);
142
    }
143
  });
144
});
145
```
146

147
### Event Handling
148

149
Add and remove event listeners for fullscreen changes and errors.
150

151
```javascript { .api }
152
/**
153
 * Add listener for fullscreen events
154
 * @param name - Event name ('change' or 'error')
155
 * @param handler - Event handler function
156
 */
157
on(name: EventName, handler: (event: Event) => void): void;
158

159
/**
160
 * Remove previously registered event listener
161
 * @param name - Event name ('change' or 'error')
162
 * @param handler - Event handler function to remove
163
 */
164
off(name: EventName, handler: (event: Event) => void): void;
165

166
/**
167
 * Alias for .on('change', handler)
168
 * @param handler - Change event handler
169
 */
170
onchange(handler: (event: Event) => void): void;
171

172
/**
173
 * Alias for .on('error', handler)
174
 * @param handler - Error event handler
175
 */
176
onerror(handler: (event: Event) => void): void;
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
import screenfull from 'screenfull';
183

184
// Listen for fullscreen changes
185
const changeHandler = () => {
186
  console.log('Fullscreen state changed:', screenfull.isFullscreen);
187
};
188

189
screenfull.on('change', changeHandler);
190

191
// Listen for fullscreen errors
192
screenfull.on('error', event => {
193
  console.error('Fullscreen error:', event);
194
});
195

196
// Remove event listener
197
screenfull.off('change', changeHandler);
198

199
// Using alias methods
200
screenfull.onchange(() => console.log('Changed!'));
201
screenfull.onerror(err => console.error(err));
202
```
203

204
### State Properties
205

206
Read-only properties for checking fullscreen state and capabilities.
207

208
```javascript { .api }
209
/**
210
 * Whether fullscreen is currently active
211
 */
212
readonly isFullscreen: boolean;
213

214
/**
215
 * The element currently in fullscreen, otherwise undefined
216
 */
217
readonly element: Element | undefined;
218

219
/**
220
 * Whether fullscreen is supported and allowed in current context
221
 */
222
readonly isEnabled: boolean;
223

224
/**
225
 * Raw browser-specific properties used internally
226
 */    
227
raw: RawEventNames;
228
```
229

230
**Usage Examples:**
231

232
```javascript
233
import screenfull from 'screenfull';
234

235
// Check if fullscreen is supported
236
if (screenfull.isEnabled) {
237
  console.log('Fullscreen is supported');
238
}
239

240
// Check current state
241
if (screenfull.isFullscreen) {
242
  console.log('Currently in fullscreen mode');
243
  console.log('Fullscreen element:', screenfull.element);
244
}
245

246
// Access raw browser APIs (advanced usage)
247
if (screenfull.raw) {
248
  console.log('Request method:', screenfull.raw.requestFullscreen);
249
}
250
```
251

252
## Types
253

254
```javascript { .api }
255
/**
256
 * Valid event names for event handling
257
 */
258
type EventName = 'change' | 'error';
259

260
/**
261
 * Raw browser-specific fullscreen API method names
262
 */
263
interface RawEventNames {
264
  readonly requestFullscreen: string;
265
  readonly exitFullscreen: string;
266
  readonly fullscreenElement: string;
267
  readonly fullscreenEnabled: string;
268
  readonly fullscreenchange: string;
269
  readonly fullscreenerror: string;
270
}
271
```
272

273
## Browser Support & Limitations
274

275
- **Supported browsers**: All modern browsers with Fullscreen API support
276
- **iPhone limitation**: Not supported on iPhone (Safari browser limitation, not Screenfull)
277
- **User activation required**: Fullscreen requests must be initiated by user events (click, touch, key)
278
- **iframe considerations**: Requires `allowfullscreen` attribute (+ vendor prefixes) on iframe elements
279
- **Environment detection**: Use `screenfull.isEnabled` to check for support before calling methods
280

281
## Error Handling
282

283
When fullscreen is not supported, screenfull becomes `{isEnabled: false}`. Always check `screenfull.isEnabled` before calling any methods:
284

285
```javascript
286
import screenfull from 'screenfull';
287

288
if (screenfull.isEnabled) {
289
  // Safe to use fullscreen methods
290
  screenfull.request().catch(error => {
291
    console.error('Fullscreen request failed:', error);
292
  });
293
} else {
294
  console.log('Fullscreen not supported');
295
}
296
```