requestFullscreen

A cross-browser fullscreen API wrapper that provides a unified interface for handling fullscreen functionality across different browser vendors.

Features

• 🔄 Cross-browser compatible - Automatically detects and adapts to different browser's fullscreen API implementations
• 📦 Lightweight - Contains only necessary functionality encapsulation
• 🎯 Easy to use - Provides simple and intuitive API interface
• 🔧 Auto-enhancement - Automatically adds fullscreen methods to Element and Document prototypes

Supported Browser Prefixes

This library automatically detects and supports the following browser-prefixed fullscreen APIs:

• Standard implementation: requestFullscreen, exitFullscreen, fullscreenElement, fullscreenEnabled
• New WebKit: webkitRequestFullscreen, webkitExitFullscreen, webkitFullscreenElement, webkitFullscreenEnabled
• Old WebKit: webkitRequestFullScreen, webkitCancelFullScreen, webkitCurrentFullScreenElement
• Mozilla: mozRequestFullScreen, mozCancelFullScreen, mozFullScreenElement, mozFullScreenEnabled
• Microsoft: msRequestFullscreen, msExitFullscreen, msFullscreenElement, msFullscreenEnabled

Installation

npm install requestFullscreen

Usage

Basic Usage

import requestFullscreen from 'requestFullscreen';

// Request element to enter fullscreen
element.requestFullscreen();

// Exit fullscreen
document.exitFullscreen();

// Listen for fullscreen state changes
requestFullscreen.on('change', () => {
  if (document.fullscreenElement) {
    console.log('Entered fullscreen mode');
  } else {
    console.log('Exited fullscreen mode');
  }
});

// Listen for fullscreen errors
requestFullscreen.on('error', (event) => {
  console.error('Fullscreen operation failed:', event);
});

Alternative Import Methods

// Method 1: Default import
import requestFullscreen from 'requestFullscreen';
requestFullscreen.on('change', handler);

// Method 2: Named imports
import { on, off } from 'requestFullscreen';
on('change', handler);

// Method 3: Namespace import
import * as fullscreen from 'requestFullscreen';
fullscreen.on('change', handler);

Check Fullscreen Support

if (document.fullscreenEnabled) {
  console.log('Browser supports fullscreen functionality');
}

Get Current Fullscreen Element

const fullscreenElement = document.fullscreenElement;
if (fullscreenElement) {
  console.log('Current fullscreen element:', fullscreenElement);
}

Using Fullscreen Options

// Request fullscreen with navigation UI options (if supported by browser)
element.requestFullscreen({ navigationUI: 'hide' });

API Reference

Element.prototype.requestFullscreen(options)

Requests the element to enter fullscreen mode.

Parameters:

• options (Object, optional): Fullscreen options configuration
  • navigationUI (string): Controls how the browser's navigation UI is displayed
    • 'auto': Browser decides to show or hide navigation UI (default)
    • 'hide': Attempt to hide navigation UI
    • 'show': Attempt to show navigation UI

Returns:

• Promise: Promise object for the fullscreen operation

Document.prototype.exitFullscreen()

Exits fullscreen mode.

Returns:

• Promise: Promise object for the exit fullscreen operation

Document.prototype.fullscreenElement

Gets the element that is currently in fullscreen state.

Returns:

• Element|null: The current fullscreen element, or null if none

Document.prototype.fullscreenEnabled

Checks if the browser supports fullscreen functionality.

Returns:

• boolean: Whether fullscreen functionality is supported

requestFullscreen.on(event, callback)

Listens for fullscreen-related events.

Parameters:

• event (string): Event type ('change' | 'error')
• callback (Function): Event callback function

requestFullscreen.off(event, callback)

Removes fullscreen-related event listeners.

Parameters:

• event (string): Event type ('change' | 'error')
• callback (Function): Callback function to remove

Browser Compatibility

Supports all modern browsers, including:

• Chrome 50+
• Firefox 47+
• Safari 10+
• Edge 79+
• Internet Explorer 11

Notes

1. Fullscreen operations must be triggered by user interaction (such as click events)
2. Fullscreen API works more reliably in HTTPS environments
3. Mobile browsers have limited support for fullscreen API
4. Check document.fullscreenEnabled before use to confirm browser support

TypeScript Support

This library includes TypeScript definitions. When using with TypeScript, you'll get full type checking and IntelliSense support.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

MIT

Author

Created and maintained with ❤️ by jvy