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
```