MediaViewport
Inspects application-owned media with bounded zoom, pan, fit and keyboard alternatives.
See it and copy it
Framework example
Choose Astro, React, or Elements to compare native usage against the shared visual output. Each example assumes the framework-level setup is already complete.
Zoom in to inspect details. Drag to pan, or use the pan buttons and arrow keys. Home fits the image.
View MediaViewport code
Framework usage
Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.---
import { Image, MediaViewport } from '@santi020k/lumen-astro'
---
<MediaViewport label="Inspect the illustrative landscape" ratio={1.6}>
<Image alt="A landscape illustration with mountains and a lake" height={600} radius="none" src="/comparison-after.svg" width={960} />
</MediaViewport>
<p>Zoom in to inspect details. Drag to pan, or use the pan buttons and arrow keys. Home fits the image.</p>import { Image, MediaViewport } from '@santi020k/lumen-react'
export const Example = () => (
<>
<MediaViewport label="Inspect the illustrative landscape" ratio={1.6}>
<Image alt="A landscape illustration with mountains and a lake" height={600} radius="none" src="/comparison-after.svg" width={960} />
</MediaViewport>
<p>Zoom in to inspect details. Drag to pan, or use the pan buttons and arrow keys. Home fits the image.</p>
</>
)<script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements()
</script>
<lumen-media-viewport label="Inspect the illustrative landscape" ratio="1.6">
<lumen-image alt="A landscape illustration with mountains and a lake" height="600" radius="none" src="/comparison-after.svg" width="960"></lumen-image>
</lumen-media-viewport>
<p>Zoom in to inspect details. Drag to pan, or use the pan buttons and arrow keys. Home fits the image.</p>Choose your target
Add this component
Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.
pnpm add @santi020k/lumen-astropnpm add @santi020k/lumen-astrolumen add MediaViewportlumen add MediaViewportpnpm add @santi020k/lumen-reactpnpm add @santi020k/lumen-reactlumen add MediaViewport --target reactlumen add MediaViewport --target reactpnpm add @santi020k/lumen-elementspnpm add @santi020k/lumen-elementslumen add MediaViewport --target elementslumen add MediaViewport --target elementsAPI reference
Lumen-specific props and runtime attributes for the Astro primitive. Use the framework differences above and the copyable examples for React composition and Elements attributes; the public adapter types define their supported contracts.
| Attribute | Values | Default | Description |
|---|---|---|---|
| label / labels | string / Partial<LumenMediaViewportLabels> | required / English action labels | Names the preview and localizes visible actions. Elements exposes a labels property. |
| value / defaultValue | LumenMediaViewportValue / Partial<LumenMediaViewportValue> | fit at zoom 1 | Zoom is relative to fit; x and y are bounded fractions (-1 to 1) of the pan extent. React value is controlled; defaultValue initializes local state. Astro value initializes data-zoom, data-pan-x and data-pan-y. Elements value is a reflected property. |
| maxZoom / ratio | number | 4 / 16:9 | Zoom limits normalize into 1–16. Preview ratio accepts 0.1–10; invalid ratios fall back to 16:9. Elements uses max-zoom. |
| onValueChange | (value: LumenMediaViewportValue) => void | - | React callback; Astro and Elements emit ui:media-viewport-change with { zoom, x, y }. |
| disabled / locale | boolean / string | false / environment locale | Disables gestures and actions; formats visible zoom percentage. Astro actions stay disabled until enhancement. |
| children | media content | required | Supplies an image or noninteractive media view with meaningful alternative text. Loading, caching, retries and editing remain consumer-owned. |
| class, className | string | "" | Merges custom classes with the generated ui-* root classes. |
| ...native attributes | HTML attributes | - | Forwards standard attributes to the root element unless the component consumes them. |
Keyboard interactions
Keyboard behavior provided by the Astro UIPrimitives runtime for this component.
| Key | Action |
|---|---|
| + / - | Zoom in or out while the viewport is focused. |
| Arrow keys | Pan the zoomed media. |
| Home | Fit the media and reset pan. |
Runtime events
CustomEvents dispatched by the Astro UIPrimitives runtime for this component.
| Event | Target | Detail | When |
|---|---|---|---|
| ui:media-viewport-change | MediaViewport root | { zoom: number, x: number, y: number } | Reports an accepted zoom, pan or fit interaction. |