General

Media

Low-level responsive image primitive backed by `nuxt-image`.

Loading playground

Overview

Media is the low-level responsive image primitive. It takes a Media value and uses nuxt-image to pick the right variant for the current viewport, handling <picture> source selection, custom aspectRatio (boolean, string, or number), and breakpoint-aware sizes strings. The bonus cmw (content-max-width) unit makes sizes strings inside constrained containers easier to write.

Reach for MediaPreview when you also want lightbox interaction, surface-tone awareness, and cross-image navigation. Use Media directly only when you do not want the lightbox shell.

Key Business & UX Benefits

Backed by nuxt-image, so every storefront image ships in the right format and size for the device, cutting bandwidth costs and load times.
A single discriminated Media value covers images, video posters, and CDN variants, so connector code stays simple as new sources are added.
The cmw unit makes sizes strings inside constrained containers easy to write, so the layout engine picks the smallest correct asset.

Feature List

Backed by nuxt-image, so every storefront asset ships in the right format and size for the current device
Single typed `Media` value (discriminated union) covers images, video posters, and CDN variants from connectors
`aspectRatio` accepts boolean, string, or number, so callers pick between intrinsic, square, and named ratios from the same prop
Breakpoint-aware `sizes` strings hint the browser to pick the smallest correct variant, cutting bandwidth on mobile
Custom `cmw` (content-max-width) unit in `sizes` strings is honored inside constrained containers
Handles `<picture>` source selection so AVIF, WebP, and JPEG fallbacks are emitted correctly

API Reference

Prop	Default	Type
`media`	`toMedia("/no-media-provided.svg", 1, 1)`	`Media`
`alt`		`string` Override default alt passed in media object.
`aspectRatio`		`string \| number \| boolean` Aspect-ratio as string in format 4:3 or 4/3. It's also possible to pass a number. When passed `true`, the element will use the images original aspect-ratio if possible. Note that `true` selects the first media source for calculation. (Order of types has to stay as is, boolean first. Required for shorthand to work.)
`sizes`		`string` Specify responsive sizes. This is a space-separated list of screen size/width pairs. Uses laioutr-ui breakpoints.
`retina`	`false`	`boolean` Pass true to enable retina (2x density) images. Disabled by default.
`width`		`string \| number` Specify width of the image
`height`		`string \| number` Specify height of the image
`loading`		`"lazy" \| "eager"` This is a native attribute that provides a hint to the browser on how to handle the loading of an image which is outside the viewport. Defaults to 'lazy' for performance reasons.
`preload`	`false`	`boolean` In case you want to preload the image, use this prop. This will place a corresponding `link` tag in the page's head.
`fetchpriority`		`"auto" \| "low" \| "high"` This is a native attribute that provides a hint to the browser on how to prioritize the loading of an image. This value is also used for the `link` header tag, when preload is used.
`desktopBreakpoint`	`md`	`number \| BreakpointName \| (string & {})` Specify the breakpoint at which the image should be displayed as a desktop image. Can be either a pre-defined breakpoint key (like 'lg') or a number (width in pixels).

Edit this pageorReport an issue

Loading Spinner

An animated spinner indicating loading or processing state.

Navigation Bullets

A navigation bullets component