Metadata

Resolved content title for the player store

Resolves the title of the playing content into a single contentTitle value your UI can render.

Three sources can supply a title, and each keeps its own value: the one you set, the one the media reports, and the fallback you supply. The feature publishes the first one that has a value, in that order, and an empty string when none does. Because the tiers are independent, clearing the title you set reveals the media’s title rather than the empty string.

An empty string is a value, not an absence — set it and contentTitle becomes ''. Pass null to clear a tier instead.

The media tier comes from media that reports a contentData.title and emits contentdatachange. Not every source does, and a source that reports other content data doesn’t necessarily report a title — when none arrives, the media tier simply never contributes and the resolved title is whatever you set. Detaching the media clears its title; the values you set survive, so they still apply to the next source.

The metadata feature is included by the videoFeatures, audioFeatures, liveVideoFeatures, and liveAudioFeatures bundles; apps that build a custom bundle can compose it in directly.

API Reference

Configuration

Props the player provider accepts. They exist only while this feature is selected.

Prop	Type	Default
`contentTitle`	`undefined \| null \| string`	`undefined`
Description The title to display. Takes precedence over the media's title.
`defaultContentTitle`	`undefined \| null \| string`	`undefined`
Description Fallback used when neither the user nor the media supplies a title.

State

Property	Type	Details
`contentTitle`	`string`
Description The resolved content title.

Actions

Action	Type	Details
`setContentTitle`	`(value: null \| string) => void`
Description Set or clear the user title override.
`setDefaultContentTitle`	`(value: null \| string) => void`
Description Set or clear the fallback used when neither the user nor media supplies a title.

Set the title

Both inputs are props on Player.Provider. A player built without the metadata feature has neither prop, and neither is forwarded.

import { createPlayer } from '@videojs/react';
import { videoFeatures } from '@videojs/react/video';

const Player = createPlayer({ features: videoFeatures });

function App({ episode }: { episode: { title: string | null } }) {
  return (
    <Player.Provider contentTitle={episode.title} defaultContentTitle="Untitled episode">
      <Player.Container>
        <video src="episode.mp4" />
      </Player.Container>
    </Player.Provider>
  );
}

Both inputs are attributes on the provider element, each with a matching property. A player built without the metadata feature observes neither attribute.

<video-player content-title="The Pilot" default-content-title="Untitled episode">
  <media-container>
    <video src="episode.mp4"></video>
  </media-container>
</video-player>

Removing an attribute clears that tier. Setting the property does not write the attribute back, so read the property — not the attribute — for the current value.

const player = document.querySelector('video-player')!;

player.contentTitle = 'The Pilot';
player.removeAttribute('content-title'); // falls back to the media, then the default

Configuration is one way: writing setContentTitle or setDefaultContentTitle on the store updates the same tiers, but never writes back to the prop or attribute. Pick one or the other for a given title.

Selector

Pass selectMetadata to usePlayer to subscribe to metadata state. Returns undefined if the metadata feature is not configured.

import { selectMetadata, usePlayer } from '@videojs/react';

function ContentTitle() {
  const metadata = usePlayer(selectMetadata);
  if (!metadata?.contentTitle) return null;

  return <h2 className="content-title">{metadata.contentTitle}</h2>;
}

import { createPlayer, MediaElement, selectMetadata } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController, context } = createPlayer({ features: videoFeatures });

class ContentTitle extends MediaElement {
  readonly #metadata = new PlayerController(this, context, selectMetadata);
}