> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: MediaOverlay Component

## Article: MediaOverlay Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/media/media-overlay-component.md

## Article Content:

# MediaOverlay

_Components/Media/MediaOverlay_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/mediaoverlay>

## Overview

```jsx
<StorybookComponents.Stack width="25%">
  <Proportion aspectRatio={1}>
    <MediaOverlay skin="gradient" media="FoodExample1.jpg">
      <MediaOverlay.Content placement="top-end" visible="hover">
        <IconButton priority="secondary" size="tiny">
          <Icons.Star />
        </IconButton>
        <PopoverMenu
          triggerElement={
            <IconButton priority="secondary" size="tiny">
              <Icons.More />
            </IconButton>
          }
        >
          <PopoverMenu.MenuItem text="Edit" />
          <PopoverMenu.MenuItem text="Preview" />
          <PopoverMenu.MenuItem text="Remove" skin="destructive" />
        </PopoverMenu>
      </MediaOverlay.Content>
      <MediaOverlay.Content placement="top-start" visible="always">
        <Badge skin="success">New!</Badge>
      </MediaOverlay.Content>
      <MediaOverlay.Content placement="bottom-start" visible="always">
        <Text size="small" weight="normal" light>
          Breakfast toast
        </Text>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
</StorybookComponents.Stack>;
```

Media overlay is a container that allows users to place any content on top of a media such as an image or a video.

### Do

- Use it to place a badge, text or other content on top of a media.
- Use it to reveal duration or other static data on media element hover.
- Use it to reveal related actions on media element hover.

### Don't

- Don't use it to display plain images. Use `<Image/>` or `<ImageViewer/>` instead.

### Feature examples

#### Structure

Component consists of two main containers:\
 - `<MediaOverlay>` - a parent container that accepts image or video content via \`media\` prop.\
 - `<MediaOverlay.Content>` - child container that accepts items that should be displayed on top of a media as child elements.

```jsx
<Proportion aspectRatio={2}>
  <MediaOverlay
    hoverSkin="dark"
    media={
      <StorybookComponents.Stack
        justifyContent="center"
        alignItems="center"
        height="100%"
      >
        Area for the media content
      </StorybookComponents.Stack>
    }
  >
    <MediaOverlay.Content visible="hover">
      <StorybookComponents.Placeholder skin="light">
        Area for overlay elements
      </StorybookComponents.Placeholder>
    </MediaOverlay.Content>
  </MediaOverlay>
</Proportion>;
```

#### Overlay content placement

Control the position of overlay elements with placement prop. It supports 5 positions:\
 - \`top-start\`\
 - \`top-end\`\
 - \`middle\`\
 - \`bottom-start\`\
 - \`bottom-end\`

```jsx
<Proportion aspectRatio={2}>
  <MediaOverlay skin="gradient" media={<StorybookComponents.Placeholder />}>
    <MediaOverlay.Content placement="top-start" visible="always">
      <StorybookComponents.Placeholder>
        Top Start
      </StorybookComponents.Placeholder>
    </MediaOverlay.Content>
    <MediaOverlay.Content placement="top-end" visible="always">
      <StorybookComponents.Placeholder>Top End</StorybookComponents.Placeholder>
    </MediaOverlay.Content>
    <MediaOverlay.Content placement="middle" visible="always">
      <StorybookComponents.Placeholder>Middle</StorybookComponents.Placeholder>
    </MediaOverlay.Content>
    <MediaOverlay.Content placement="bottom-start" visible="always">
      <StorybookComponents.Placeholder>
        Bottom Start
      </StorybookComponents.Placeholder>
    </MediaOverlay.Content>
    <MediaOverlay.Content placement="bottom-end" visible="always">
      <StorybookComponents.Placeholder>
        Bottom End
      </StorybookComponents.Placeholder>
    </MediaOverlay.Content>
  </MediaOverlay>
</Proportion>;
```

#### Initial overlay skin

Control initial overlay type with \`skin\` prop. It supports 3 skins:\
 - \`none\` (default) - use when no visual overlay is required.\
 - \`gradient\` - use it when relevant data needs to be visible in a default state of the element.\
 - \`dark\` - use it when media underneath is less important, e.g. as a last item in galleries with a total number or images on top.

```jsx
<StorybookComponents.Stack>
  <Proportion>
    <MediaOverlay skin="none" media="example.jpg">
      <MediaOverlay.Content visible="always">None</MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
  <Proportion>
    <MediaOverlay skin="gradient" media="example.jpg">
      <MediaOverlay.Content visible="always">Gradient</MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
  <Proportion>
    <MediaOverlay skin="dark" media="example.jpg">
      <MediaOverlay.Content visible="always">
        <Box color="D80">Dark</Box>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
</StorybookComponents.Stack>;
```

#### Hover overlay skin

Control hover overlay type with \`hoverSkin\` prop. It supports 3 skins:\
 - \`none\` (default) - use for static media items.\
 - \`gradient\` - use it when hovered item must remain visible, but overlaid content needs a contrast.\
 - \`dark\` - use it to bring the maximum contrast of relevant content on interactive element hover.

```jsx
<StorybookComponents.Stack>
  <Proportion>
    <MediaOverlay hoverSkin="none" media="example.jpg">
      <MediaOverlay.Content visible="always">None</MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
  <Proportion>
    <MediaOverlay hoverSkin="gradient" media="example.jpg">
      <MediaOverlay.Content visible="always">Gradient</MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
  <Proportion>
    <MediaOverlay hoverSkin="dark" media="example.jpg">
      <MediaOverlay.Content visible="always">Dark</MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
</StorybookComponents.Stack>;
```

#### Overlay content visibility

Specify when overlay content should be revealed for the user with visible prop. It supports 3 values:\
 - \`default\` (default) - use it to hide overlay content on element hover.\
 - \`hover\` - use it to reveal overlay content on element hover.\
 - \`always\` - use it to display overlay content all the time.

```jsx
<StorybookComponents.Stack>
  <Proportion>
    <MediaOverlay media="example.jpg">
      <MediaOverlay.Content visible="default">
        <StorybookComponents.Placeholder>
          Visible in initial state
        </StorybookComponents.Placeholder>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
  <Proportion>
    <MediaOverlay media="example.jpg">
      <MediaOverlay.Content visible="hover">
        <StorybookComponents.Placeholder>
          Visible on hover
        </StorybookComponents.Placeholder>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
  <Proportion>
    <MediaOverlay media="example.jpg">
      <MediaOverlay.Content visible="always">
        <StorybookComponents.Placeholder>
          Always visible
        </StorybookComponents.Placeholder>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
</StorybookComponents.Stack>;
```

#### Border radius

Define border radius in pixels with \`borderRadius\` prop. Get rid of a default border radius with \`removeRoundedBorders\` prop.

```jsx
<StorybookComponents.Stack>
  <Proportion>
    <MediaOverlay media="example.jpg" removeRoundedBorders />
  </Proportion>
  <Proportion>
    <MediaOverlay media="example.jpg" borderRadius="18px" />
  </Proportion>
  <Proportion>
    <MediaOverlay media="example.jpg" borderRadius="42px" />
  </Proportion>
</StorybookComponents.Stack>;
```

#### Custom media element

Pass a custom \`media\` element with media prop.

```jsx
<StorybookComponents.Stack width="25%">
  <Proportion aspectRatio={1.4}>
    <MediaOverlay
      skin="gradient"
      media={
        <FillPreview fill="linear-gradient(to right top, #051937, #004d7a, #008793, #00bf72, #a8eb12)" />
      }
    >
      <MediaOverlay.Content placement="bottom-start" visible="always">
        <Text size="small" ellipsis light>
          Item Title
        </Text>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
</StorybookComponents.Stack>;
```

#### Drag handle

Use a compound `<MediaOverlay.DragHandle/>` component for reorderable components. Actions should be placed at the top right corner in this scenario.

```jsx
<StorybookComponents.Stack width="33%">
  <Proportion aspectRatio={1.4}>
    <MediaOverlay hoverSkin="dark" media="example.jpg">
      <MediaOverlay.Content placement="top-end" visible="hover">
        <IconButton priority="secondary" skin="inverted" size="tiny">
          <Icons.Crop />
        </IconButton>
        <IconButton priority="secondary" skin="inverted" size="tiny">
          <Icons.Star />
        </IconButton>
        <PopoverMenu
          triggerElement={
            <IconButton priority="secondary" skin="inverted" size="tiny">
              <Icons.More />
            </IconButton>
          }
        >
          <PopoverMenu.MenuItem text="Edit" />
          <PopoverMenu.MenuItem text="Preview" />
          <PopoverMenu.MenuItem text="Remove" skin="destructive" />
        </PopoverMenu>
      </MediaOverlay.Content>
      <MediaOverlay.Content visible="hover">
        <MediaOverlay.DragHandle />
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
</StorybookComponents.Stack>;
```

### Common use case examples

#### Social media gallery

Use media overlay to place identifying data, such as logo or video duration on top of a media item.

```jsx
<Box gap="30px">
  <Proportion aspectRatio={1.5}>
    <MediaOverlay skin="gradient" media="TravelExample7.jpg">
      <MediaOverlay.Content placement="bottom-start" visible="always">
        <Icons.Instagram style={{ color: 'white' }} />
      </MediaOverlay.Content>
      <MediaOverlay.Content placement="bottom-end" visible="always">
        <Text size="small" light>
          02:32
        </Text>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
  <Proportion aspectRatio={1.5}>
    <MediaOverlay skin="gradient" media="TravelExample8.jpg">
      <MediaOverlay.Content placement="bottom-start" visible="always">
        <Icons.Instagram style={{ color: 'white' }} />
      </MediaOverlay.Content>
      <MediaOverlay.Content placement="bottom-end" visible="always">
        <Text size="small" light>
          01:21
        </Text>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
  <Proportion aspectRatio={1.5}>
    <MediaOverlay skin="gradient" media="TravelExample9.jpg">
      <MediaOverlay.Content placement="bottom-start" visible="always">
        <Icons.Instagram style={{ color: 'white' }} />
      </MediaOverlay.Content>
      <MediaOverlay.Content placement="bottom-end" visible="always">
        <Text size="small" light>
          00:43
        </Text>
      </MediaOverlay.Content>
    </MediaOverlay>
  </Proportion>
</Box>;
```

#### Item lists

Use media overlay to list down visual items, such as dishes, that can be edited, marked as favourite or interacted with in any other way.

```jsx
() => {
  const Controls = () => [
    <IconButton priority="secondary" skin="inverted" size="tiny">
      <Icons.Star />
    </IconButton>,
    <PopoverMenu
      triggerElement={
        <IconButton priority="secondary" skin="inverted" size="tiny">
          <Icons.More />
        </IconButton>
      }
    >
      <PopoverMenu.MenuItem text="Edit" />
      <PopoverMenu.MenuItem text="Preview" />
      <PopoverMenu.MenuItem text="Remove" skin="destructive" />
    </PopoverMenu>,
  ];

  return (
    <Box gap="30px">
      <Proportion aspectRatio={1}>
        <MediaOverlay skin="gradient" media="FoodExample1.jpg">
          <MediaOverlay.Content placement="top-end" visible="hover">
            <Controls />
          </MediaOverlay.Content>
          <MediaOverlay.Content placement="top-start" visible="always">
            <Badge skin="success">New!</Badge>
          </MediaOverlay.Content>
          <MediaOverlay.Content placement="bottom-start" visible="always">
            <Text size="small" weight="normal" light>
              Breakfast toast
            </Text>
          </MediaOverlay.Content>
        </MediaOverlay>
      </Proportion>
      <Proportion aspectRatio={1}>
        <MediaOverlay skin="gradient" media="FoodExample2.jpg">
          <MediaOverlay.Content placement="top-end" visible="hover">
            <Controls />
          </MediaOverlay.Content>
          <MediaOverlay.Content placement="top-start" visible="always">
            <Badge skin="neutralStandard">Popular</Badge>
          </MediaOverlay.Content>
          <MediaOverlay.Content placement="bottom-start" visible="always">
            <Text size="small" weight="normal" light>
              Lemon Ricotta Pasta
            </Text>
          </MediaOverlay.Content>
        </MediaOverlay>
      </Proportion>
      <Proportion aspectRatio={1}>
        <MediaOverlay skin="gradient" media="FoodExample3.jpg">
          <MediaOverlay.Content placement="top-end" visible="hover">
            <Controls />
          </MediaOverlay.Content>
          <MediaOverlay.Content placement="bottom-start" visible="always">
            <Text size="small" weight="normal" light>
              Spanish Paella
            </Text>
          </MediaOverlay.Content>
        </MediaOverlay>
      </Proportion>
    </Box>
  );
};
```

#### Image gallery

Use media overlay to place static data on top of an image, e.g. to place a counter indicating how many more images there are.

```jsx
<Layout gap="18px">
  <Cell span={6} rows={2}>
    <Image height="381px" src="TravelExample1.jpg" />
  </Cell>
  <Cell span={3}>
    <Image height="180px" src="TravelExample2.jpg" />
  </Cell>
  <Cell span={3}>
    <Image height="180px" src="TravelExample3.jpg" />
  </Cell>
  <Cell span={3}>
    <Image height="180px" src="TravelExample4.jpg" />
  </Cell>
  <Cell span={3}>
    <Box height="180px">
      <MediaOverlay skin="dark" onClick={() => {}} media="TravelExample5.jpg">
        <MediaOverlay.Content visible="always">
          <Heading light size="medium">
            +128
          </Heading>
        </MediaOverlay.Content>
      </MediaOverlay>
    </Box>
  </Cell>
</Layout>;
```

#### Content edit

Use media overlay to store actions related to that media element, such as edit, refresh or delete.

```jsx
<Proportion aspectRatio={1.6}>
  <MediaOverlay hoverSkin="dark" media="TravelExample6.jpg">
    <MediaOverlay.Content visible="hover">
      <Box gap="12px" align="center">
        <Button prefixIcon={<Icons.Refresh />}>Change Image</Button>
        <Tooltip content="Delete">
          <IconButton priority="secondary">
            <Icons.Delete />
          </IconButton>
        </Tooltip>
      </Box>
    </MediaOverlay.Content>
  </MediaOverlay>
</Proportion>;
```

#### Reordable list

Use middle placement at the center to position recordable element indication. This function should use a compound `<MediaOverlay.DragHandle/>` component.

```jsx
() => {
  const Media = ({ img }) => (
    <Proportion aspectRatio={1}>
      <MediaOverlay hoverSkin="dark" media={img}>
        <MediaOverlay.Content placement="top-end" visible="hover">
          <IconButton priority="secondary" skin="inverted" size="tiny">
            <Icons.Crop />
          </IconButton>
          <IconButton priority="secondary" skin="inverted" size="tiny">
            <Icons.Star />
          </IconButton>
          <PopoverMenu
            triggerElement={
              <IconButton priority="secondary" skin="inverted" size="tiny">
                <Icons.More />
              </IconButton>
            }
          >
            <PopoverMenu.MenuItem text="Edit" />
            <PopoverMenu.MenuItem text="Preview" />
            <PopoverMenu.MenuItem text="Remove" skin="destructive" />
          </PopoverMenu>
        </MediaOverlay.Content>
        <MediaOverlay.Content visible="hover">
          <MediaOverlay.DragHandle />
        </MediaOverlay.Content>
      </MediaOverlay>
    </Proportion>
  );

  return (
    <Box gap="30px">
      <Media img="FoodExample4.jpg" />
      <Media img="FoodExample5.jpg" />
      <Media img="FoodExample6.jpg" />
    </Box>
  );
};
```

#### Video Player

Use MediaOverlay as a video player by setting \`isVideo\` prop to true and providing a video source via \`videoSrc\` prop. The component will automatically display play/pause controls and handle video playback.

```jsx
<Proportion aspectRatio={16 / 9}>
  <MediaOverlay
    isVideo
    videoSrc="https://www.w3schools.com/html/mov_bbb.mp4"
    hoverSkin="dark"
  >
    <MediaOverlay.Content placement="bottom-start" visible="always">
      <Text size="small" light>
        Big Buck Bunny
      </Text>
    </MediaOverlay.Content>
    <MediaOverlay.Content placement="bottom-end" visible="always">
      <Text size="small" light>
        02:15
      </Text>
    </MediaOverlay.Content>
  </MediaOverlay>
</Proportion>;
```

## Code

```jsx
import { MediaOverlay } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaHidden` | `boolean` | — | Adding aria-hidden="true" to an element removes that element and all of its children from the accessibility tree. |
| `borderRadius` | `string \| number` | — | Control border radius of the media container. |
| `bottomStrip` | `boolean` | `false` | When `true` on mobile, a `middle` placement renders as a bottom strip and the bottom placements move above it. |
| `children` | `ReactNode` | — | Accepts any component as `<MediaOverlay.Content>` content. Each element has the following properties: - `visible` - define when to display this content. Possible values are: - `default` (default) - content is visible only when not hovered. - `hover` - content is visible only when hovered. - `always` - content is always visible. - `placement` - define where to place this content. Possible values are `top-start`, `top-end`, `middle` (default), `bottom-end` and `bottom-start`. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `hovered` | `boolean` | — | Toggles hover state in a controlled mode. |
| `hoverSkin` | `"none" \| "dark" \| "gradient"` | — | Sets a hover overlay skin. |
| `isVideo` | `boolean` | — | Indicates if the media is a video element. When true, displays play/pause controls. |
| `media` | `ReactNode` | — | Accept image URL or a custom node as a media background. Not needed when `isVideo` is set and `videoSrc` is passed. |
| `onClick` | `() => void` | — | Defines a click handler. When provided, component will be clickable and will have a pointer cursor on hover. |
| `removeRoundedBorders` | `boolean` | — | Removes a default borders radius. |
| `showPlayButton` | `boolean` | `true` | Controls visibility of the play button overlay. Only applies when isVideo is true. |
| `skin` | `"none" \| "dark" \| "gradient"` | `'none'` | Sets a default overlay skin. |
| `videoProps` | `VideoHTMLAttributes<HTMLVideoElement>` | — | Additional props to pass to the video element. |
| `videoSrc` | `string` | — | Video element source URL. Only used when isVideo is true. |

## Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

## Changelog

- **1.344.0** (2026-10-28) — maintenance release, no component-specific changes
- **1.342.0** (2026-10-26) — breaking: the video play button is now a medium dark primary button in every theme. In Harmony (odeditor), the content padding is 12px on every side, the gradient and dark skins follow the new overlay style with a blurred dark hover, and overlays keep the media's rounded corners. ([#17462](invalid-url)) — has visual changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.315.0** (2026-08-20) — fix: custom element media (such as `Proportion`) sizes the component again in auto-height containers; in 1.314.0 it collapsed to the minimum height. ([#16855](invalid-url)) — has visual changes
- **1.314.0** (2026-08-19) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.295.0** (2026-07-03) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — feat: add bottomStrip prop ([#16422](invalid-url)) — has visual changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.254.0** (2026-02-03) — feat: add video playback ([#15871](invalid-url))
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.243.0** (2025-12-23) — feat: enhance DragHandle to support buttonProps for accessibility ([#15716](invalid-url))
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.204.1** (2025-07-09) — fix: unreachable interactive content by keyboard and SR ([#15025](invalid-url))
- **1.200.0** (2025-06-17) — breaking: tokenization ([#14911](invalid-url))
- **1.154.0** (2025-01-17) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes