Install. Configure. Play.
The whole video.
Your own space.
A sharp poster, centered playback and an optional blurred background. Configure everything below with simple HTML attributes.
1. Install two files
Copy src/gennix-video.js and src/gennix-video.css to your web server. Adjust these paths to your installation. No dependencies, npm install or build required. Serve through HTTP(S).
<link rel="stylesheet" href="/gennix-video/src/gennix-video.css">
<script src="/gennix-video/src/gennix-video.js" defer></script>2. Add a video
<gennix-video size="fullwidth" aspect-ratio="16/9"
max-height="80dvh" background="poster"
provider="youtube" src="HuACikeyg0c">
</gennix-video>The × closes the video and restores its poster. It overlays the corner without reducing player height. Use close-button="false" to hide it.
Fullwidth
Fills the parent width. Height follows 16/9. Change aspect-ratio to reserve another shape.
<gennix-video id="inline-video" size="fullwidth" aspect-ratio="16/9" provider="youtube" src="HuACikeyg0c" max-height="80dvh" background="poster" aria-label="YouTube inline"></gennix-video>Custom dimensions
900 × 500 pixels, reduced in width to fit a smaller parent. Use height="auto" for a ratio-derived height.
<gennix-video size="custom" width="900" height="500" provider="native" src="assets/sample.mp4" poster="assets/sample-poster.jpg" background="poster"></gennix-video>Vertical video
Native metadata keeps all four edges visible, without changing the reserved height.
<gennix-video size="custom" width="900" height="400" provider="native" src="assets/portrait.mp4" poster="assets/portrait-poster.jpg" background="poster"></gennix-video>Square video
Declare the known ratio to reserve the right space before loading.
<gennix-video size="custom" width="400" height="auto" aspect-ratio="1/1" provider="native" src="assets/square.mp4" poster="assets/square-poster.jpg"></gennix-video>Native cover
Cover crops the picture to fill the box. YouTube always stays contained.
<gennix-video size="custom" width="900" height="300" fit="cover" provider="native" src="assets/portrait.mp4" poster="assets/portrait-poster.jpg"></gennix-video>Configuration reference
Boolean values: empty or true enables; false disables. Missing or unknown values use the default. Playback attributes are read when preparing a new player; reset before changing a loaded player. Size attributes update immediately.
| Attribute | Default | Values and behavior |
|---|---|---|
provider | youtube | youtube or native. |
src | Required | YouTube ID or full watch, youtu.be, embed or shorts URL; native HTTP(S) URL or relative file path. |
poster | YouTube thumbnail; none for native | Poster image URL. Use a local image to avoid an initial remote thumbnail request. |
size | fullwidth | fullwidth, custom or viewport. Fullwidth fills the parent width, not necessarily the entire browser. |
aspect-ratio | 16/9 | Reserved box ratio, e.g. 4/3, 1/1 or 9/16. Native metadata adjusts the player ratio without changing the box. |
width | 100% | Custom width: positive pixels (900 or 900px), or a percentage greater than 0 and at most 100%. |
height | auto | Custom height: positive pixels or auto. Fixed height stays fixed on narrow screens. |
max-height | No extra limit | Positive pixels, vh, dvh or svh. Example: 80dvh. Modern viewport units fall back to vh when unsupported. |
viewport-offset | 0 | Non-negative pixels subtracted from viewport height or an explicit max-height. Applied once. If greater than the limit, height becomes zero. |
background | poster for custom/viewport; solid for fullwidth | poster enables a blurred static background; solid uses a color; none is transparent. |
fit | contain | contain shows the whole video. cover crops native video only; YouTube always uses contain. |
template | inline | Legacy inline or hero layout. Explicit size is recommended and takes precedence. |
controls | true | Show original player controls. When false, provide your own pause control if needed. |
muted | false | Start without sound. |
loop | false | Repeat; takes precedence over on-end. Native looping returns to the beginning of the file. |
autoplay | false | Request playback on connection. Allows initial loading; browser policy may still block playback. |
start | URL time or 0 | Initial position in whole seconds or h/m/s format, e.g. 1m30s. Explicit start (including 0) overrides URL start, t or #t. |
poster-click | false | Allow clicking the poster to play; the keyboard-accessible Play button remains available. |
pause-others | false | Pause other connected instances only after this one actually starts. Set on both for mutual coordination. |
on-end | keep | keep retains the player; poster resets to the poster after emitting ended. Ignored while looping. |
play-button | true | false loads the player and exposes original controls without an initial click. Cannot combine with controls=false unless a custom Play button exists. |
close-button | true | Show an overlay × during loading and playback. Closing resets to the poster without restarting autoplay. No label attribute; internal accessible name is Close video. |
fullscreen | false | Show a real full-screen toggle. Reserves a 48px bottom toolbar; unrelated to viewport sizing. |
playsinline | true | Request inline playback on mobile. false permits the browser’s native full-screen behavior. |
preload | none | Native hint: none, metadata or auto, after creating the video. No-button passive mode uses auto to expose working controls. |
playlabel | Play | Generated Play button text; supports language suffixes such as playlabel-fr. |
play-content | both | both, text or icon. Icon-only buttons retain an accessible name. |
button-background | #fff | Button background color. |
button-color | #172026 | Button text/icon color. |
button-hover-background | #e3f5a4 | Background on hover. |
button-hover-color | #172026 | Text/icon color on hover. |
button-focus-background | #e3f5a4 | Background with keyboard focus. |
button-focus-color | #172026 | Text/icon color with keyboard focus. |
button-radius | 100 | Non-negative radius in pixels, e.g. 12. |
lang | Not set | Explicit language takes priority. Normalizes en_US to en-us. |
lang-cookie | Not set | Name of an existing site cookie to read. Never creates or modifies cookies. |
aria-label | Generic player name | Accessible name for the component and embedded player; does not replace playlabel. |
loadinglabel | Loading video… | Configurable text; also accepts language suffixes, e.g. loadinglabel-fr. |
errorlabel | Unable to load the video. | Configurable text; also accepts language suffixes, e.g. errorlabel-fr. |
retrylabel | Retry | Configurable text; also accepts language suffixes, e.g. retrylabel-fr. |
fullscreenlabel | Full screen | Configurable text; also accepts language suffixes, e.g. fullscreenlabel-fr. |
exitfullscreenlabel | Exit full screen | Configurable text; also accepts language suffixes, e.g. exitfullscreenlabel-fr. |
blockedlabel | Press Play to start the video. | Configurable text; also accepts language suffixes, e.g. blockedlabel-fr. |
fullscreenerrorlabel | The browser did not allow full screen. | Configurable text; also accepts language suffixes, e.g. fullscreenerrorlabel-fr. |
Language fallback
Regional translation → base language → unsuffixed attribute → built-in English text. A configured cookie is read only; never created or modified. Missing playlabel falls back to Play. See the language demo for full examples.
Methods and events
play() and requestFullscreen() return promises. pause(), reset() and refreshLanguage() are synchronous. Events: gennix:statechange, gennix:ready, gennix:play, gennix:pause, gennix:ended and gennix:error. Read the README for contracts and optional CSS customization.