@videojs/element

⚠️ Beta Close to stable. Experimental adoption in real projects.

A lightweight reactive custom element base class for Video.js. Type-aligned with Lit's ReactiveElement but stripped down to only what we use.

npm install @videojs/element

Why?

Video.js web components used @lit/reactive-element but only needed a fraction of its API — reactive properties, batched updates, and controllers. The rest (Shadow DOM, static styles, decorators, complex attribute converters, shouldUpdate, custom scheduling) shipped as dead code (~2.8 kB brotli).

@videojs/element provides the same programming model at ~840 B brotli.

Quick Start

import { ReactiveElement } from '@videojs/element';
import type { PropertyValues } from '@videojs/element';

class MyElement extends ReactiveElement {
  static override properties = {
    label: { type: String },
    disabled: { type: Boolean },
  };

  label = 'Click me';
  disabled = false;

  protected override update(changed: PropertyValues): void {
    super.update(changed);
    this.textContent = this.label;
  }
}

customElements.define('my-element', MyElement);

Alignment with Lit

The API is a subset of Lit's ReactiveElement. Types are aligned so controllers written for Lit work with @videojs/element without changes.

What's included

• static properties — Declare reactive properties with type (String, Boolean, Number) and attribute (custom attribute name)
• Reactive accessors — Installed automatically, change detection via Object.is()
• Batched updates — Multiple property changes in one tick trigger a single update via queueMicrotask()
• Full lifecycle — willUpdate → update → firstUpdated (first time) → updated → updateComplete
• hasUpdated — false until first update completes, true during firstUpdated and updated (matches Lit)
• isUpdatePending — true while an update is queued or in progress
• performUpdate() — Synchronously flush a pending update
• scheduleUpdate() — Override point for custom update timing (default calls performUpdate())
• Reactive controllers — addController/removeController with hostConnected, hostDisconnected, hostUpdate, hostUpdated
• Element upgrade handling — Properties set before registration are preserved

What's NOT included

| Lit feature | Why excluded | |---|---| | Shadow DOM / createRenderRoot() | We use light DOM exclusively | | static styles / CSS adoption | No shadow root to adopt into | | Decorators (@property, @state) | We use static properties | | shouldUpdate() | No use case for skipping updates | | getUpdateComplete() | No async update chaining needed | | reflect option | No property-to-attribute reflection | | converter option | Simple type coercion is sufficient | | state option | All properties are observable | | hasChanged option | Object.is() is always used |

Property inheritance

Lit walks the prototype chain to collect properties from all ancestors. We don't — subclasses that define their own static properties must spread the parent:

class FancyButton extends MyButton {
  static override properties = {
    ...MyButton.properties,
    variant: { type: String },
  };
}

This is only needed when a subclass declares static properties. If it doesn't, JS static property inheritance means the parent's properties are used automatically.

Context

Context is re-exported from @lit/context — the same implementation used across the Lit ecosystem:

import { createContext, ContextProvider, ContextConsumer } from '@videojs/element/context';

This provides tree-scoped data sharing without prop drilling, using Lit's Context Protocol.

Community

If you need help with anything related to Video.js v10, or if you'd like to casually chat with other members:

• Join Discord Server
• See GitHub Discussions

License

Apache-2.0