fullscreen-control Web Component

A web component to progressively enhance any video or iframe element with fullscreen capabilities.

Demo

• Live Demo (Source)
• esm.sh CDN Demo (Source)
• unpkg CDN Demo (Source)

Installation

npm install @aarongustafson/fullscreen-control

Usage

Option 1: Import the class and define manually

Import the class and define the custom element with your preferred tag name:

import { FullscreenControlElement } from '@aarongustafson/fullscreen-control';

customElements.define('my-custom-name', FullscreenControlElement);

Option 2: Auto-define the custom element (browser environments only)

Use the guarded definition helper to register the element when customElements is available:

import '@aarongustafson/fullscreen-control/define.js';

If you prefer to control when the element is registered, call the helper directly:

import { defineFullscreenControl } from '@aarongustafson/fullscreen-control/define.js';

defineFullscreenControl();

You can also include the guarded script from HTML:

<script src="./node_modules/@aarongustafson/fullscreen-control/define.js" type="module"></script>

Basic Example

<fullscreen-control>
  <video src="video.mp4"></video>
</fullscreen-control>

Or with an iframe:

<fullscreen-control button-text="View {name} fullscreen">
  <iframe src="https://example.com" title="Product teaser"></iframe>
</fullscreen-control>

TypeScript

This package ships bundled TypeScript definitions. Importing either @aarongustafson/fullscreen-control or @aarongustafson/fullscreen-control/fullscreen-control.js provides typed access to FullscreenControlElement along with its fullscreen-control:enter and fullscreen-control:exit events.

Accessibility

The component automatically manages focus for keyboard accessibility. When the fullscreen button is clicked to enter fullscreen mode, focus will automatically return to the button after exiting fullscreen, ensuring a seamless keyboard navigation experience. The control also links the button to the wrapped media via aria-controls, generating a unique id for the slotted element when it does not already have one.

Both button-text and button-label support the {name} placeholder. If the slotted video or iframe has an accessible name (via aria-label, title, or other native naming), {name} will be replaced with that value; otherwise it resolves to an empty string.

Changes to the slotted media's accessible name or id are observed automatically, ensuring the visible button text and its aria-controls attribute remain in sync even when those attributes are updated dynamically.

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | button-text | string | "View fullscreen" | Visible text for the fullscreen button. Supports {name} to inject the slotted media's accessible name. | | button-label | string | "" (falls back to button-text) | Optional aria-label for the fullscreen button. Supports {name}. Only set this when the screen reader announcement should differ from the visible text; otherwise omit it so it mirrors button-text. |

Events

The component fires custom events that you can listen to:

| Event | Description | Detail | |-------|-------------|--------| | fullscreen-control:enter | Fired when entering fullscreen mode | CustomEvent | | fullscreen-control:exit | Fired when exiting fullscreen mode | CustomEvent |

Example Event Handling

const element = document.querySelector('fullscreen-control');

element.addEventListener('fullscreen-control:enter', (event) => {
  console.log('Entered fullscreen');
});

element.addEventListener('fullscreen-control:exit', (event) => {
  console.log('Exited fullscreen');
});

Methods

| Method | Description | |--------|-------------| | enterFullscreen() | Programmatically enter fullscreen mode | | exitFullscreen() | Programmatically exit fullscreen mode | | toggleFullscreen() | Toggle fullscreen mode on/off |

CSS Custom Properties

The component uses light DOM, so you can style the button directly using standard CSS selectors. Additionally, two CSS custom properties are available for positioning:

| Property | Default | Description | |----------|---------|-------------| | --fullscreen-control-button-inset-block-start | 0.5rem | Block-start (top) position of the button | | --fullscreen-control-button-inset-inline-end | 0.5rem | Inline-end (right in LTR) position of the button |

Example Styling

/* Style the button directly */
fullscreen-control button {
  background: #ff6b6b;
  color: white;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 20px;
}

/* Adjust button position */
fullscreen-control {
  --fullscreen-control-button-inset-block-start: 1rem;
  --fullscreen-control-button-inset-inline-end: 1rem;
}

Browser Support

This component uses modern web standards:

• Custom Elements v1
• Shadow DOM v1
• ES Modules

For older browsers, you may need polyfills.

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# View demo
open demo/index.html

License

MIT © Aaron Gustafson