Media

Updated: May 9, 2025

Media handles responsive media content with support for lazy loading, aspect ratios, and intelligent rendering of videos or embeds. Use it for dynamic content blocks with consistent behavior.

Media

<Media
  src="/image.jpg"
  alt="Preview"
  sizes="(max-width: 768px) 100vw, 768px"
  radius="xl"
  border="neutral-alpha-medium"
/>

Loading

Show a skeleton block while content is loading. Only works when aspectRatio is specified.

Skeleton

<Media
  loading
  radius="l"
  aspectRatio="16/9"
  src="/image.jpg"
/>

Caption

The caption prop renders a ReactNode below the image, making it easy to provide additional details. It will render the image as figure and the caption as figcaption.

Caption

Vibe code with Quasar! The time is now.

<Media
  caption="Vibe code with Quasar! The time is now."
  src="/image.jpg"
  alt="Preview"
  radius="xl"
  border="neutral-alpha-medium"
/>

Enlarge

Enable full-screen zooming for images and videos.

Enlarge

<Media
  enlarge
  src="/images/docs/once-ui/vibe-coding-dark.jpg"
/>

Aspect Ratio

The Media component will automatically detect the aspect ratio of the image and set it to auto if not specified. You can provide an explicit aspect ratio using the aspectRatio prop.

Aspect Ratio

<Media
  maxWidth={24}
  aspectRatio="3/4"
  radius="l"
  src="/image.jpg"
/>

Stretch

Use the stretch prop to drop the intrinsic aspect ratio and let the media take whatever box it is in. (fill is the layout prop every component has — fillWidth and fillHeight together.)

Stretch

<Row maxWidth={18} height={8}>
  <Media
    stretch
    radius="l"
    src="/image.jpg"
  />
</Row>

Sizes shorthand

You can pass a number to sizes for a common responsive pattern. sizes={768} expands to (max-width: 768px) 100vw, 768px.

Sizes shorthand

<Media
  src="/image.jpg"
  alt="Preview"
  sizes={768}
  radius="xl"
  border="neutral-alpha-medium"
/>

YouTube

The component auto-detects and renders YouTube links, just pass a YouTube URL to the src prop.

YouTube

<Media
  src="https://www.youtube.com/watch?v=TQT_FSdxbC8"
  aspectRatio="16/9"
  autoplay={false}
  controls={true}
  sound={true}
  radius="xl"
/>

Video

For MP4 and other file-based video, set controls to render a minimal custom player with play/pause, seek, mute, and fullscreen. Keyboard shortcuts: space (play/pause), m (mute), f (fullscreen), arrow keys (seek).

Video

0:00 / 0:00

<Media
  src="/video.mp4"
  aspectRatio="16/9"
  autoplay={false}
  controls
  sound
  loop={false}
  radius="xl"
/>

API reference

Prop	Type	Default
aspectRatio	string	original
height	number	—
alt	string	—
loading	boolean	false
objectFit	CSSProperties["objectFit"]	cover
enlarge	boolean	false
srcrequired	string	—
unoptimized	boolean	false
sizes	stringnumber	100vw
priority	boolean	—
caption	ReactNode	—
stretch Drop the intrinsic aspect ratio and let the media fill its box.	boolean	false
fillWidth	boolean	true
loop	boolean	true
autoplay	boolean	true
sound	boolean	false
controls	boolean	false
style	React.CSSProperties	—
className	string	—
…and every FlexProps prop	inherited	—

ComponentsIcon

ComponentsDialog

Edit this page on GitHub

Built with curiosity by Lorant One and the Design Engineers Club