Skip to content
VistaView

Native Video Extension

The Native Video extension plays direct video file URLs (blob URLs, same-origin files, signed S3/CDN URLs, or any remote .mp4/.webm/.mov URL) using the browser’s native <video> element, instead of embedding a third-party platform player.

Installation

Section titled “Installation”

ESM (Module Bundlers)

Section titled “ESM (Module Bundlers)”
import { vistaView } from 'vistaview';
import { nativeVideo } from 'vistaview/extensions/native-video';
import 'vistaview/style.css';

vistaView({
  elements: [{ src: '/videos/clip.mp4', poster: '/thumbnails/clip.jpg' }],
  extensions: [nativeVideo()],
});

UMD (CDN)

Section titled “UMD (CDN)”
<script src="https://unpkg.com/vistaview/main/dist/vistaview.umd.js"></script>
<script src="https://unpkg.com/vistaview/extensions/native-video/dist/main.umd.cjs"></script>

<script>
  VistaView.vistaView({
    elements: [{ src: '/videos/clip.mp4', poster: '/thumbnails/clip.jpg' }],
    extensions: [VistaView.nativeVideo()],
  });
</script>

Usage

Section titled “Usage”

Gallery items are passed as config objects (not DOM elements), so elements takes an array directly:

import { vistaView } from 'vistaview';
import { nativeVideo } from 'vistaview/extensions/native-video';
import 'vistaview/style.css';

vistaView({
  elements: [
    { src: '/photos/1.jpg', alt: 'Photo 1' },
    { src: '/videos/clip.mp4', poster: '/thumbnails/clip.jpg', type: 'video' },
    { src: 'https://cdn.example.com/signed-video.mov', poster: '/thumbnails/clip2.jpg' },
  ],
  extensions: [nativeVideo()],
});
  • src - the video file URL (blob URL, same-origin path, or remote URL)
  • poster - optional thumbnail/poster image shown before playback
  • type - optional. Set to 'video' to force detection when the URL doesn’t end in a recognizable video extension (e.g. a signed URL with no file extension)

Detection

Section titled “Detection”

An item is treated as a native video when either:

  • it has an explicit type: 'video' marker, or
  • its src ends in a known video extension (.mp4, .webm, .ogg, .mov, .m4v, optionally followed by a query string or hash), or
  • its src is a blob: URL

Otherwise the item is treated as a regular image.

Video Size

Section titled “Video Size”

The extension creates videos with a maximum width of 800px (or window width, whichever is smaller) while maintaining a 16:9 aspect ratio, matching the other video extensions.

Features

Section titled “Features”
  • Native controls - Uses the browser’s built-in <video controls> element
  • Lazy loading - preload="metadata" avoids downloading the full file for videos preloaded ahead of the current item
  • Responsive sizing - Videos maintain a 16:9 aspect ratio, same as the other video extensions
  • Cleanup on navigation - The video is paused and released when navigating away or closing the lightbox

Bundle Size

Section titled “Bundle Size”
  • ESM: 2.73 KB (1.27 KB gzip)
  • UMD: 2.46 KB (1.23 KB gzip)

Limitations

Section titled “Limitations”
  • No zoom controls - Videos cannot be pinch/drag-zoomed like images, matching the other video extensions
  • Object URL lifecycle - if src is a blob: URL, the extension never calls URL.revokeObjectURL on it; the caller that created the blob owns revoking it

Next Steps

Section titled “Next Steps”