# custom-media-element

> A custom element for extending the native media elements ( or )

Latest version **1.4.6** (published 2026-03-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install custom-media-element
pnpm add custom-media-element
yarn add custom-media-element
bun add custom-media-element
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.4.6 |
| Published | 2026-03-19 |
| First published | 2023-05-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 33.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 264 |
| Author | @muxinc |
| Maintainers | luwes, mux-npmjs |
| Keywords | custom, element, video, audio, media, web, component |

## Links

- npm: https://www.npmjs.com/package/custom-media-element
- Repository: https://github.com/muxinc/media-elements
- Homepage: https://github.com/muxinc/media-elements#readme
- Issues: https://github.com/muxinc/media-elements/issues
- npm.io page: https://npm.io/package/custom-media-element

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.4.6 (latest) — 2026-03-19
- 1.0.2-canary.2 (canary) — 2023-10-29
- 1.4.5 — 2025-06-09
- 1.4.4 — 2025-06-07
- 1.4.3 — 2025-05-23
- 1.4.2 — 2024-12-20
- 1.4.1 — 2024-11-26
- 1.4.0 — 2024-11-26
- 1.3.3 — 2024-11-25
- 1.3.2 — 2024-06-07
- 1.3.1 — 2024-05-24
- 1.3.0 — 2024-05-08
- 1.2.3 — 2024-02-07
- 1.2.2 — 2023-12-21
- 1.2.1 — 2023-12-21
- … 20 more at https://npm.io/package/custom-media-element/versions

## README

# Custom Media Element

[![NPM Version](https://img.shields.io/npm/v/custom-media-element?style=flat-square&color=informational)](https://www.npmjs.com/package/custom-media-element) 
[![NPM Downloads](https://img.shields.io/npm/dm/custom-media-element?style=flat-square&color=informational&label=npm)](https://www.npmjs.com/package/custom-media-element) 
[![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/custom-media-element?style=flat-square&color=%23FF5627)](https://www.jsdelivr.com/package/npm/custom-media-element)
[![npm bundle size](https://img.shields.io/bundlephobia/minzip/custom-media-element?style=flat-square&color=success&label=gzip)](https://bundlephobia.com/result?p=custom-media-element) 
[![Codecov](https://img.shields.io/codecov/c/github/muxinc/custom-media-element?style=flat-square)](https://app.codecov.io/gh/muxinc/custom-media-element)

A custom element for extending the native media elements (`<audio>` or `<video>`).


## Usage

```js
import { CustomVideoElement } from 'custom-media-element';

class MyCustomVideoElement extends CustomVideoElement {
  constructor() {
    super();
  }

  // Override the play method.
  play() {
    return super.play()
  }

  // Override the src getter & setter.
  get src() {
    return super.src;
  }

  set src(src) {
    super.src = src;
  }
}

if (globalThis.customElements && !globalThis.customElements.get('my-custom-video')) {
  globalThis.customElements.define('my-custom-video', MyCustomVideoElement);
}

export default MyCustomVideoElement;
```

```html
<my-custom-video
  src="https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/low.mp4"
></my-custom-video>
```


## Interfaces

```ts
export const Events: string[];

export const audioTemplate: HTMLTemplateElement;
export const videoTemplate: HTMLTemplateElement;

export class CustomAudioElement extends HTMLAudioElement implements HTMLAudioElement {
  static readonly observedAttributes: string[];
  static Events: string[];
  static template: HTMLTemplateElement;
  readonly nativeEl: HTMLAudioElement;
  attributeChangedCallback(attrName: string, oldValue?: string | null, newValue?: string | null): void;
  connectedCallback(): void;
  disconnectedCallback(): void;
  handleEvent(event: Event): void;
}

export class CustomVideoElement extends HTMLVideoElement implements HTMLVideoElement {
  static readonly observedAttributes: string[];
  static Events: string[];
  static template: HTMLTemplateElement;
  readonly nativeEl: HTMLVideoElement;
  attributeChangedCallback(attrName: string, oldValue?: string | null, newValue?: string | null): void;
  connectedCallback(): void;
  disconnectedCallback(): void;
  handleEvent(event: Event): void;
}

type CustomMediaElementConstructor<T> = {
  readonly observedAttributes: string[];
  Events: string[];
  template: HTMLTemplateElement;
  new(): T
};

export function CustomMediaMixin(superclass: any, options: { tag: 'video', is?: string }):
  CustomMediaElementConstructor<CustomVideoElement>;

export function CustomMediaMixin(superclass: any, options: { tag: 'audio', is?: string }):
  CustomMediaElementConstructor<CustomAudioElement>;
```


## Related

- [Media Chrome](https://github.com/muxinc/media-chrome) Your media player's dancing suit. 🕺
- [`<hls-video>`](https://github.com/muxinc/media-elements/tree/main/packages/hls-video-element) A custom element for playing HTTP Live Streaming (HLS) videos.
- [`<youtube-video>`](https://github.com/muxinc/media-elements/tree/main/packages/youtube-video-element) A custom element for the YouTube player.
- [`<vimeo-video>`](https://github.com/muxinc/media-elements/tree/main/packages/vimeo-video-element) A custom element for the Vimeo player.
- [`<spotify-audio>`](https://github.com/muxinc/media-elements/tree/main/packages/spotify-audio-element) A custom element for the Spotify player.
- [`<jwplayer-video>`](https://github.com/muxinc/media-elements/tree/main/packages/jwplayer-video-element) A custom element for the JW player.
- [`<wistia-video>`](https://github.com/muxinc/media-elements/tree/main/packages/wistia-video-element) A custom element for the Wistia player.
- [`<cloudflare-video>`](https://github.com/muxinc/media-elements/tree/main/packages/cloudflare-video-element) A custom element for the Cloudflare player.
- [`<videojs-video>`](https://github.com/muxinc/media-elements/tree/main/packages/videojs-video-element) A custom element for Video.js.
- [`<castable-video>`](https://github.com/muxinc/media-elements/tree/main/packages/castable-video) Cast your video element to the big screen with ease!
- [`<mux-player>`](https://github.com/muxinc/elements/tree/main/packages/mux-player) The official Mux-flavored video player custom element.
- [`<mux-video>`](https://github.com/muxinc/elements/tree/main/packages/mux-video) A Mux-flavored HTML5 video element w/ hls.js and Mux data builtin.

---
_Source: https://npm.io/package/custom-media-element · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._