VideoOverlay
Quick answer
L.videoOverlay plays a video across a geographic bounds rectangle and accepts one URL, a list of format alternatives or an existing video element. It inherits image overlay geometry handling and adds autoplay, loop, muting and aspect ratio options. Videos respect pane stacking, so they can sit below or above vector layers.
L.videoOverlay( video , bounds , options ) → VideoOverlay
Key points
- keepAspectRatio prevents distortion when bounds proportions differ from the video.
- getElement returns the video node for play, pause and mute through native APIs.
- playsInline keeps mobile playback inside the map instead of opening a fullscreen player.
Example
var bounds = [[39.895, 116.378], [39.920, 116.405]];
var video = L.videoOverlay(
['/media/flow.webm', '/media/flow.mp4'],
bounds,
{ opacity: 0.75, autoplay: true, loop: true, muted: true }
).addTo(map);
/* 浏览器允许静音自动播放，带声音的 autoplay 会被拦截 */
var el = video.getElement();
el.muted = true;
el.play().catch(function () {
console.warn('自动播放被拦截，等待用户交互');
});
document.getElementById('toggle').addEventListener('click', function () {
el.paused ? el.play() : el.pause();
});Notes
- Browsers block audible autoplay, so muted true or a user gesture is required.
- Options such as autoplay and muted are ignored when you pass an existing video element.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). VideoOverlay. https://www.jingweizhi.com/en/leaflet/api/video-overlay.html (accessed 2026-11-03).