Components/Media/MediaOverlay
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/mediaoverlay
Media overlay is a container that allows users to place any content on top of a media such as an image or a video.
<Image/> or <ImageViewer/> instead.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.
Control the position of overlay elements with placement prop. It supports 5 positions:
 - `top-start`
 - `top-end`
 - `middle`
 - `bottom-start`
 - `bottom-end`
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.
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.
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.
Define border radius in pixels with `borderRadius` prop. Get rid of a default border radius with `removeRoundedBorders` prop.
Pass a custom `media` element with media prop.
Use a compound <MediaOverlay.DragHandle/> component for reorderable components. Actions should be placed at the top right corner in this scenario.
Use media overlay to place identifying data, such as logo or video duration on top of a media item.
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.
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.
Use media overlay to store actions related to that media element, such as edit, refresh or delete.
Use middle placement at the center to position recordable element indication. This function should use a compound <MediaOverlay.DragHandle/> component.
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.
| 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. |
No testkit for this component — it doesn't expose a unidriver testkit.
Proportion) sizes the component again in auto-height containers; in 1.314.0 it collapsed to the minimum height. (#16855) — has visual changesLast updated: 30 October 2026