# Background preset

The background video preset — a player, feature bundle, skin, and media for ambient video with no controls

`@videojs/html/background` is the preset for ambient background video with no user controls. It bundles the `<background-video-player>` element, the `backgroundFeatures` bundle it is configured with, one chrome-less skin, and the `<background-video>` media component, which autoplays, mutes, and loops. See [Presets](https://videojs.org/docs/framework/html/guides/presets) for how presets fit together and [Background video](https://videojs.org/docs/framework/html/guides/background-video) for building one.

## Import

```ts
import '@videojs/html/background/player';
import '@videojs/html/background/skin';
import '@videojs/html/background/video';
```

Or load the [CDN](https://videojs.org/docs/framework/html/guides/cdn) bundle that registers all three:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/background.js"></script>
```

Unlike the other presets, the background preset has one bundle and no player-only bundle.

## Usage

**index.html**

```html
<script type="module">
  import '@videojs/html/background/player';
  import '@videojs/html/background/skin';
  import '@videojs/html/background/video';
</script>

<background-video-player>
  <background-video-skin>
    <background-video src="hero.mp4"></background-video>
  </background-video-skin>
</background-video-player>
```

## Player

`@videojs/html/background/player` registers `<background-video-player>`, whose class is `BackgroundVideoPlayerElement`. It is a [player](https://videojs.org/docs/framework/html/reference/components/player) element created by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) with `backgroundFeatures`. It owns the player store but no layout. Put the skin or a [`<media-container>`](https://videojs.org/docs/framework/html/reference/components/player-container) inside it.

| Attribute | Property | Description |
| --- | --- | --- |
| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |

The bundle has no feature that takes player inputs, so the element has no player-input attributes such as `content-title` or `poster`; `keep-alive` is the only attribute it reads. Its read-only `store` property returns its player store.

The preset root also exports a `PlayerController` bound to the background player’s store. Use it from any custom element inside `<background-video-player>`; see [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller).

## Feature bundle

`backgroundFeatures` is the array of [features](https://videojs.org/docs/framework/html/guides/features) the player is configured with. The background media component handles autoplay, muting, and looping on its own:

`backgroundFeatures` is currently empty, so the player's store holds no feature state or actions.

Its type, `BackgroundFeatures`, is the matching empty tuple. Import it from the package root:

```ts
import type { BackgroundFeatures } from '@videojs/html';
```

To add a feature, pass your own array to `createPlayer`. For example, add playback to drive a play button over the background video:

```ts
import { createPlayer, playbackFeature } from '@videojs/html';
import { backgroundFeatures } from '@videojs/html/background';

const { PlayerElement } = createPlayer({
  features: [...backgroundFeatures, playbackFeature],
});

customElements.define('my-background-player', PlayerElement);
```

## Skins

- [BackgroundVideoSkin](https://videojs.org/docs/framework/html/reference/components/background-video-skin) — the only skin, a chrome-less surface that sizes the video and renders no controls.

## Media

`@videojs/html/background/video` registers [`<background-video>`](https://videojs.org/docs/framework/html/reference/components/background-video), which renders a `<video>` inside shadow DOM that is muted, looped, and autoplaying by default. It is the same registration as `@videojs/html/media/background-video`. For HLS or Mux sources, use [`<hls-background-video>`](https://videojs.org/docs/framework/html/reference/components/hls-background-video) or [`<mux-background-video>`](https://videojs.org/docs/framework/html/reference/components/mux-background-video) instead.

## Exports

The preset root, `@videojs/html/background`, has no side effects. Importing it never registers an element:

| Export | Description |
| --- | --- |
| `BackgroundVideoPlayerElement` | The [player](#player) element class. |
| `PlayerController` | The player controller, bound to the background player’s store. |
| `backgroundFeatures` | The [feature bundle](#feature-bundle). |
| `BackgroundVideoSkinElement` | The [skin](#skins) element class. |

Registration entry points are side-effect-only:

| Entry point | Registers |
| --- | --- |
| `@videojs/html/background/player` | `<background-video-player>` |
| `@videojs/html/background/skin` | `<background-video-skin>` and `<media-container>` |
| `@videojs/html/background/video` | `<background-video>` |

---

HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt