---
title: Poster
frameworkTitle:
  html: media-poster
description: Poster image component that displays a thumbnail until video playback starts
---

import ComponentReference from "@/components/docs/api-reference/ComponentReference.astro";
import FrameworkCase from "@/components/docs/FrameworkCase.astro";
import StyleCase from "@/components/docs/StyleCase.astro";
import Demo from "@/components/docs/demos/Demo.astro";

{/* React demos */}
import BasicUsageDemoReact from "@/components/docs/demos/poster/react/css/BasicUsage";
import basicUsageReactTsx from "@/components/docs/demos/poster/react/css/BasicUsage.tsx?raw";
import basicUsageReactCss from "@/components/docs/demos/poster/react/css/BasicUsage.css?raw";

{/* HTML demos */}
import BasicUsageDemoHtml from "@/components/docs/demos/poster/html/css/BasicUsage.astro";
import basicUsageHtml from "@/components/docs/demos/poster/html/css/BasicUsage.html?raw";
import basicUsageHtmlCss from "@/components/docs/demos/poster/html/css/BasicUsage.css?raw";
import basicUsageHtmlTs from "@/components/docs/demos/poster/html/css/BasicUsage.ts?raw";

## Anatomy

Import the component:

<FrameworkCase frameworks={["react"]}>
  ```tsx
  <Poster src="poster.jpg" alt="Video preview" />
  ```
</FrameworkCase>

<FrameworkCase frameworks={["html"]}>
  ```html
  <media-poster>
    <img src="poster.jpg" alt="Video preview" />
  </media-poster>
  ```
</FrameworkCase>

## Behavior

The poster is visible before playback starts. Once the user plays or seeks, the poster hides permanently — pausing does not bring it back. The poster reappears when a new source is loaded.

## Styling

Style the poster with the `[data-visible]` attribute:

<FrameworkCase frameworks={["html"]}>
```css
media-poster:not([data-visible]) {
  display: none;
}
```
</FrameworkCase>

<FrameworkCase frameworks={["react"]}>
React renders an `<img>` element. Add a `className` to style it:

```css
.poster:not([data-visible]) {
  display: none;
}
```
</FrameworkCase>

You control the child `<img>` — this means `srcset`, `sizes`, `loading="lazy"`, and framework image components all work naturally.

## Accessibility

Unlike the native `<video poster>` attribute, this component allows you to provide accessible text alternatives for screen readers via the `alt` attribute on your child `<img>`. This means you can describe the poster image (e.g., `alt="Keynote speaker at a conference"`) or mark it as decorative with `alt=""` if it doesn't convey meaningful information. 

## Examples

### Basic Usage

<FrameworkCase frameworks={["react"]}>
  <StyleCase styles={["css"]}>
    <Demo
      files={[
        { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
        { title: "App.css", code: basicUsageReactCss, lang: "css" },
      ]}
    >
      <BasicUsageDemoReact client:idle />
    </Demo>
  </StyleCase>
</FrameworkCase>

<FrameworkCase frameworks={["html"]}>
  <StyleCase styles={["css"]}>
    <Demo
      files={[
        { title: "index.html", code: basicUsageHtml, lang: "html" },
        { title: "index.css", code: basicUsageHtmlCss, lang: "css" },
        { title: "index.ts", code: basicUsageHtmlTs, lang: "ts" },
      ]}
    >
      <BasicUsageDemoHtml />
    </Demo>
  </StyleCase>
</FrameworkCase>

<ComponentReference component="Poster" />
