MediaOverlay

Components/Media/MediaOverlay

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

Overview

Copy

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.

Copy

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`

Copy

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.

Copy

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.

Copy

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.

Copy

Border radius

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

Copy

Custom media element

Pass a custom `media` element with media prop.

Copy

Drag handle

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

Copy

Common use case examples

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

Copy

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.

Copy

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.

Copy

Content edit

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

Copy

Reordable list

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

Copy

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaHiddenboolean—Adding aria-hidden="true" to an element removes that element and all of its children from the accessibility tree.
borderRadiusstring | number—Control border radius of the media container.
bottomStripbooleanfalseWhen true on mobile, a middle placement renders as a bottom strip and the bottom placements move above it.
childrenReactNode—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.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
hoveredboolean—Toggles hover state in a controlled mode.
hoverSkin"none" | "dark" | "gradient"—Sets a hover overlay skin.
isVideoboolean—Indicates if the media is a video element. When true, displays play/pause controls.
mediaReactNode—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.
removeRoundedBordersboolean—Removes a default borders radius.
showPlayButtonbooleantrueControls visibility of the play button overlay. Only applies when isVideo is true.
skin"none" | "dark" | "gradient"'none'Sets a default overlay skin.
videoPropsVideoHTMLAttributes<HTMLVideoElement>—Additional props to pass to the video element.
videoSrcstring—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) — 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) — 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) — 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)
  • 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)
  • 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)
  • 1.200.0 (2025-06-17) — breaking: tokenization (#14911)
  • 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

Last updated: 30 October 2026

Did this help?