MediaWrapper

MediaWrapper frames media in the same border, radius and aspect ratio as Image, and turns a poster into a play button. MediaOverlay puts a poster image over a video or an embed, and MediaOverlayIcon draws the play icon on it. Activating the wrapper hides the overlay and starts the video.

import { Image, MediaOverlay, MediaOverlayIcon, MediaWrapper, Video } from '@systhemaui/next'

export default function Demo() {
  return (
    <div className="w-full max-w-3xl">
      <MediaWrapper aspectRatio="16/9" playAffordance>
        <Video src="/demo-assets/loop.mp4" controls deferControls deferControlsLabel={null} />
        <MediaOverlay>
          <Image src="/demo-assets/loop-poster.webp" alt="" width={1280} height={720} />
          <MediaOverlayIcon />
        </MediaOverlay>
      </MediaWrapper>
    </div>
  )
}

ImportLink to this section

import { MediaOverlay, MediaOverlayIcon, MediaWrapper } from '@systhemaui/next'

In a React app without Next.js, import them from @systhemaui/react.

Variants and tagsLink to this section

The play affordanceLink to this section

The wrapper is a play button only when it wraps something playable. It inspects its direct children (and any fragments or arrays around them) and takes role="button", tabIndex={0} and an aria-label only when it finds a <Video>, a <MediaOverlay> poster or a plain <video>. That matches where core's CSS shows cursor: pointer. A still image, a map or another embed stays out of the tab order instead of announcing a "Play video" button that does nothing.

When activated (click, Enter or Space on the wrapper itself), the wrapper:

1. sets data-playing="true", which fades the MediaOverlay out and lets clicks through to the media,
2. calls onPlayChange(true),
3. calls play() on every <video> inside it.

Once playing, the wrapper drops the button role, so the native video controls take over.

Set playAffordance for a composition the detector cannot see through: a custom component that renders a <video> internally, or any wrapper you render in a Server Component. There the Video and MediaOverlay children reach the wrapper as client references, which the detector does not recognize, so the examples on this page that have no hooks set playAffordance explicitly. playAffordance={false} states that a wrapper is inert.

ExamplesLink to this section

Poster over an embedLink to this section

An embed you cannot script, such as a cross-origin <iframe>, can still sit behind a poster. Listen to onPlayChange and mount the embed when the visitor activates the wrapper, so its scripts load only on demand.

import { useState } from 'react'
import { Image, MediaOverlay, MediaOverlayIcon, MediaWrapper, Video } from '@systhemaui/next'

export default function Demo() {
  const [playing, setPlaying] = useState(false)

  return (
    <div className="w-full max-w-3xl">
      <MediaWrapper aspectRatio="16/9" onPlayChange={setPlaying} playVideoLabel="Play the tour">
        {playing ? <Video src="/demo-assets/loop.mp4" autoPlay controls /> : null}
        <MediaOverlay>
          <Image src="/demo-assets/workspace.webp" alt="" width={1800} height={1200} />
          <MediaOverlayIcon />
        </MediaOverlay>
      </MediaWrapper>
    </div>
  )
}

In a real page, swap the Video for the embed's <iframe> with its autoplay parameter.

Linked mediaLink to this section

MediaWrapper.a makes the whole frame a link, for example to an article. It is never a play button. Inside an overlay, the poster zooms in slightly on hover.

import { Image, MediaOverlay, MediaWrapper } from '@systhemaui/next'

export default function Demo() {
  return (
    <div className="w-full max-w-md">
      <MediaWrapper.a href="#linked-media" aspectRatio="4/3" aria-label="Read the coast story">
        <MediaOverlay>
          <Image src="/demo-assets/coast.webp" alt="" width={1800} height={1200} />
        </MediaOverlay>
      </MediaWrapper.a>
    </div>
  )
}

Custom play iconLink to this section

Put your own icon in MediaOverlayIcon, or change the default for the whole project with blocks.media.overlayIcon (see Component CSS blocks). The icon is sized by --media-icon-size, and the overlay tint comes from --color-media-overlay.

import { Image, MediaOverlay, MediaOverlayIcon, MediaWrapper, Video } from '@systhemaui/next'

export default function Demo() {
  return (
    <div className="w-full max-w-3xl">
      <MediaWrapper aspectRatio="16/9" playAffordance>
        <Video src="/demo-assets/loop.mp4" controls deferControls deferControlsLabel={null} />
        <MediaOverlay>
          <Image src="/demo-assets/loop-poster.webp" alt="" width={1280} height={720} />
          <MediaOverlayIcon>
            <svg viewBox="0 -960 960 960" fill="currentColor" aria-hidden="true" focusable="false">
              <path d="m380-300 280-180-280-180v360ZM480-80q-83 0-156-31.5T197-197q-54-54-85.5-127T80-480q0-83 31.5-156T197-763q54-54 127-85.5T480-880q83 0 156 31.5T763-763q54 54 85.5 127T880-480q0 83-31.5 156T763-197q-54 54-127 85.5T480-80Z" />
            </svg>
          </MediaOverlayIcon>
        </MediaOverlay>
      </MediaWrapper>
    </div>
  )
}

PropsLink to this section

MediaWrapperLink to this section

playVideoLabel defaults to 'Play video' and names the affordance while the video is paused. A blank value falls back to the default, so the button is never nameless; unlike Video's deferControlsLabel it has no null opt-out, because the wrapper is the affordance. isPlaying makes the play state controlled. disableAnimation drops the configured animationClasses; the wrapper also switches off the scroll reveals of the media inside it, so the frame reveals as one piece.

MediaOverlay and MediaOverlayIconLink to this section

HTML and CSSLink to this section

The same structure with classes. Set data-playing="true" on the wrapper (from your own script) to fade the overlay out:

<div class="media-wrapper aspect-16/9" role="button" tabindex="0" aria-label="Play video">
  <video class="media object-cover" src="/loop.mp4" preload="metadata" playsinline></video>
  <div class="media-overlay">
    <img src="/loop-poster.webp" alt="" />
    <span class="media-overlay-icon"></span>
  </div>
</div>

An empty .media-overlay-icon draws the default play icon. While a wrapper with an overlay is not playing, it shows a pointer cursor.

Next.jsLink to this section

The @systhemaui/next twin behaves the same, with two differences:

• MediaWrapper.a renders through the Next-aware LinkHelper, so the link prefetches and navigates on the client.
• Without playVideoLabel, the label comes from the Systhema frontend message catalog (accessibility.playVideo), so it follows the page locale when frontend locales are configured.

Children are matched by element identity first and then by display name, so a Video imported from @systhemaui/react inside the Next wrapper still counts as playable. The module that defines MediaWrapper is a server module that delegates to client components, so MediaWrapper.a works when imported in a Server Component.

AccessibilityLink to this section

• The wrapper is a button only while it wraps something playable and is not yet playing. It activates on Enter and Space as well as click, and ignores key presses that bubble up from controls inside it.
• Give a wrapped Video with deferred controls deferControlsLabel={null}, so the action has one name, the wrapper's.
• Localize playVideoLabel in React; in Next.js it comes from the message catalog.
• A MediaWrapper.a with only an image inside needs a name: an aria-label, or alt text on the image.

RelatedLink to this section

• Video
• Image
• Video block