or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-screenfull

Simple wrapper for cross-browser usage of the JavaScript Fullscreen API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/screenfull@6.0.x

To install, run

npx @tessl/cli install tessl/npm-screenfull@6.0.0

index.mddocs/

Screenfull

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.

Package Information

  • Package Name: screenfull
  • Package Type: npm
  • Language: JavaScript (ES Module)
  • Installation: npm install screenfull

Core Imports

import screenfull from 'screenfull';

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

const screenfull = require('screenfull');

Basic Usage

import screenfull from 'screenfull';

// Check if fullscreen is supported
if (screenfull.isEnabled) {
  // Make the entire page fullscreen
  document.getElementById('button').addEventListener('click', () => {
    screenfull.request();
  });
  
  // Listen for fullscreen changes
  screenfull.on('change', () => {
    console.log('Am I fullscreen?', screenfull.isFullscreen ? 'Yes' : 'No');
  });
  
  // Handle fullscreen errors
  screenfull.on('error', event => {
    console.error('Failed to enable fullscreen', event);
  });
}

Architecture

Screenfull provides:

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

Capabilities

Fullscreen Request

Request fullscreen mode for an element or the entire page.

/**
 * Make an element fullscreen
 * @param element - Element to make fullscreen (defaults to document.documentElement)
 * @param options - FullscreenOptions for configuration
 * @returns Promise that resolves when element enters fullscreen
 */
request(element?: Element, options?: FullscreenOptions): Promise<void>;

Usage Examples:

import screenfull from 'screenfull';

// Fullscreen the entire page
if (screenfull.isEnabled) {
  await screenfull.request();
}

// Fullscreen a specific element
const videoElement = document.getElementById('video');
if (screenfull.isEnabled) {
  await screenfull.request(videoElement);
}

// Fullscreen with options (hide navigation UI on mobile)
const targetElement = document.getElementById('game');
if (screenfull.isEnabled) {
  await screenfull.request(targetElement, { navigationUI: 'hide' });
}

Exit Fullscreen

Exit fullscreen mode.

/**
 * Brings you out of fullscreen
 * @returns Promise that resolves after exiting fullscreen
 */
exit(): Promise<void>;

Usage Example:

import screenfull from 'screenfull';

if (screenfull.isFullscreen) {
  await screenfull.exit();
}

Toggle Fullscreen

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

/**
 * Requests fullscreen if not active, otherwise exits
 * @param element - Element to make fullscreen (defaults to document.documentElement)
 * @param options - FullscreenOptions for configuration
 * @returns Promise that resolves after entering/exiting fullscreen
 */
toggle(element?: Element, options?: FullscreenOptions): Promise<void>;

Usage Example:

import screenfull from 'screenfull';

// Toggle fullscreen on image click
document.querySelectorAll('img').forEach(img => {
  img.addEventListener('click', () => {
    if (screenfull.isEnabled) {
      screenfull.toggle(img);
    }
  });
});

Event Handling

Add and remove event listeners for fullscreen changes and errors.

/**
 * Add listener for fullscreen events
 * @param name - Event name ('change' or 'error')
 * @param handler - Event handler function
 */
on(name: EventName, handler: (event: Event) => void): void;

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

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

/**
 * Alias for .on('error', handler)
 * @param handler - Error event handler
 */
onerror(handler: (event: Event) => void): void;

Usage Examples:

import screenfull from 'screenfull';

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

screenfull.on('change', changeHandler);

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

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

// Using alias methods
screenfull.onchange(() => console.log('Changed!'));
screenfull.onerror(err => console.error(err));

State Properties

Read-only properties for checking fullscreen state and capabilities.

/**
 * Whether fullscreen is currently active
 */
readonly isFullscreen: boolean;

/**
 * The element currently in fullscreen, otherwise undefined
 */
readonly element: Element | undefined;

/**
 * Whether fullscreen is supported and allowed in current context
 */
readonly isEnabled: boolean;

/**
 * Raw browser-specific properties used internally
 */    
raw: RawEventNames;

Usage Examples:

import screenfull from 'screenfull';

// Check if fullscreen is supported
if (screenfull.isEnabled) {
  console.log('Fullscreen is supported');
}

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

// Access raw browser APIs (advanced usage)
if (screenfull.raw) {
  console.log('Request method:', screenfull.raw.requestFullscreen);
}

Types

/**
 * Valid event names for event handling
 */
type EventName = 'change' | 'error';

/**
 * Raw browser-specific fullscreen API method names
 */
interface RawEventNames {
  readonly requestFullscreen: string;
  readonly exitFullscreen: string;
  readonly fullscreenElement: string;
  readonly fullscreenEnabled: string;
  readonly fullscreenchange: string;
  readonly fullscreenerror: string;
}

Browser Support & Limitations

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

Error Handling

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

import screenfull from 'screenfull';

if (screenfull.isEnabled) {
  // Safe to use fullscreen methods
  screenfull.request().catch(error => {
    console.error('Fullscreen request failed:', error);
  });
} else {
  console.log('Fullscreen not supported');
}