# media-title

Displays the resolved content title for the current media

## Import

```ts
import '@videojs/html/ui/title';
```

## Anatomy

```html
<media-title></media-title>
```

## Behavior

The element renders the resolved title directly as text and owns that text: it replaces any authored content whenever the title updates. Set the title on the player instead.

```html
<video-player content-title="Big Buck Bunny">
  <video src="video.mp4"></video>
  <media-title></media-title>
</video-player>
```

A title can come from two places. The player uses the first one that has a value:

1. The title you set on the player.
2. The title the media reports about itself.

If neither has a value, there is nothing to show and the title hides itself.

The title is player input, not player state, so change it the way you set it in the first place. The store exposes the resolved `title` to read, and nothing to write. That resolution belongs to the [metadata feature](../api/feature-metadata.md), which the video and audio presets include.

`title` already means the tooltip on an element, so the player takes the title as `content-title`, reflected by the `contentTitle` property:

```ts
const player = document.querySelector("video-player");

player.contentTitle = "Sintel";
```

Set it to `null` to hand the title back to the media.

The component exposes `data-visible` while controls are visible. Use that hook to animate the title with the controls.

## Styling

When no title resolves, the element sets the native `hidden` attribute and `data-hidden`, so it takes up no space and a background or gradient never sits over empty space.

To fade the title in and out with the controls, use the root’s `data-visible` attribute:

```css
media-title {
  opacity: 0;
  transition: opacity 150ms ease-out;
}

media-title[data-visible] {
  opacity: 1;
}
```

## Accessibility

The title is ordinary text, so it reaches assistive technology as content with no ARIA of its own. The native `hidden` attribute it sets when there is no title also removes it from the accessibility tree, so nothing is announced when there is nothing to announce.

Fading the title out with `opacity` leaves it readable by a screen reader while it is not painted. That is deliberate — the name of what is playing stays relevant whether or not the controls happen to be on screen.

The component does not name the player. To give the player region an accessible name, set `aria-label` or `aria-labelledby` on the container yourself.

## Examples

### Basic Usage

**index.html**

```html
<video-player content-title="Big Buck Bunny">
  <media-container class="html-title-basic">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline loop></video>
    <media-title class="html-title-basic__title"></media-title>
    <media-play-button class="html-title-basic__button">
      <span class="show-when-paused">Play</span>
      <span class="show-when-playing">Pause</span>
    </media-play-button>
  </media-container>
</video-player>
```

**index.css**

```css
.html-title-basic {
  position: relative;
  display: block;
}

.html-title-basic video {
  display: block;
  width: 100%;
}

/* The element sets native `hidden` until a title resolves, so the gradient
   never sits over empty space without this demo doing anything. */
.html-title-basic__title {
  position: absolute;
  inset-inline: 0;
  top: 0;
  padding: 16px 20px 48px;
  font-size: 16px;
  font-weight: 500;
  color: white;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.5);
  pointer-events: none;
  background: linear-gradient(to bottom, rgba(0, 0, 0, 0.7), transparent);
}

.html-title-basic__button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.html-title-basic__button .show-when-paused {
  display: none;
}

.html-title-basic__button .show-when-playing {
  display: none;
}

.html-title-basic__button[data-paused] .show-when-paused {
  display: inline;
}

.html-title-basic__button:not([data-paused]) .show-when-playing {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/title';
```

## API Reference

### State

State is reflected as data attributes for CSS styling.

| Property | Type | Description |
| --- | --- | --- |
| `title` | `string` | The resolved content title. Empty when no source supplied one. |
| `hidden` | `boolean` | Whether the component is hidden because no title is available. |
| `visible` | `boolean` | Whether the player controls are visible. |

### Data attributes

| Attribute | Description |
| --- | --- |
| `data-hidden` | Present when the element is hidden because no title is available. |
| `data-visible` | Present while the player controls are visible. |