# Metadata

Resolved title and poster values for the player store

Resolves what is playing into two values your UI can render: `title` and `poster`.

`title` and `poster` each resolve independently through the same two tiers: the value you set, then the value the media reports. The first tier that holds a value wins; when neither does, the resolved value is an empty string. Because the tiers stay separate, clearing the value you set reveals the media’s, and a source that reports a poster but no title contributes to one while leaving the other empty.

An empty string counts as a value and stops the chain: set `title` to `''` and the resolved title is `''`. Pass `null` to clear your value.

The metadata feature is included by the `videoFeatures`, `audioFeatures`, `liveVideoFeatures`, and `liveAudioFeatures` [presets](https://videojs.org/docs/framework/react/guides/presets); apps that build a custom preset can compose it in directly.

## Import

```tsx
import { metadataFeature } from '@videojs/react';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/react/guides/presets) include this feature.

## API Reference

### Configuration

Props the Player component accepts. They exist only while this feature is selected.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `undefined \| null \| string` | — | The title to display. Takes precedence over the title the media carries. |
| `poster` | `undefined \| null \| string` | — | The poster to display. Takes precedence over the poster the media carries. |

### State

| Property | Type | Description |
| --- | --- | --- |
| `title` | `string` | The resolved content title. Set it through the player, not through the store. |
| `poster` | `string` | The resolved poster URL, independent of the media element's own `poster`. Set it through the player, not through the store. |

### Selector

To just show the name of what is playing, drop in the [Title component](https://videojs.org/docs/framework/react/reference/components/title) — it reads this feature for you. Reach for the selector when building your own UI.

Pass `selectMetadata` to [`usePlayer`](https://videojs.org/docs/framework/react/reference/api/use-player) to subscribe to metadata state. Returns `undefined` if the metadata feature is not configured.

**ContentTitle.tsx**

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

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

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

### Player inputs

The store publishes the resolved values and takes no writes. A player input is the only way to set one.

Every input is a prop on [`Player`](https://videojs.org/docs/framework/react/reference/components/player). A player built without the metadata feature has none of them, and none is forwarded.

**App.tsx**

```tsx
import { Container, createPlayer } from '@videojs/react';
import { videoFeatures } from '@videojs/react/video';

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

function App({ episode }: { episode: { title: string | null; art: string | null } }) {
  return (
    <Player title={episode.title} poster={episode.art}>
      <Container>
        <video src="episode.mp4" />
      </Container>
    </Player>
  );
}
```

Passing `null` clears your value, so `title={null}` falls through to the title the media reports.

### Media-reported values

The media tier comes from media that reports content data and announces changes to it, and it covers `title` and `poster`. A media reports only the keys it can vouch for, so either may be absent while the other arrives. A key that never arrives means that tier never contributes, and the resolved value is whatever you set. Detaching the media clears its values; the values you set survive and apply to the next source.

`poster` is the feature’s own resolved value, not the media element’s `poster` attribute. Setting one does not set the other.

A low-resolution stand-in to show while the poster loads is not part of this feature. The [poster](https://videojs.org/docs/framework/react/reference/components/poster) renders an `<img>` you control, so give it a `background-image` and that shows until the poster itself paints over it. [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) walks through that technique for each framework.

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
All documentation: https://videojs.org/llms.txt