cover (crop to fill)
contain (fit fully)
With placeholder, a light-gray placeholder is shown until the image finishes loading, then it switches to the image.
Default failure placeholder
Custom fallback image
With lazy, an image only starts loading when it enters the viewport; pair it with placeholder to show a "Loading" placeholder. Scroll down the list and watch the placeholder → loaded transition (images already in the viewport load immediately).
Click the image to open a full-screen preview overlay: the toolbar supports zoom in / out, rotate, flip horizontal / vertical, and download; after zooming in you can drag to pan and use the wheel to zoom. On touch screens, pinch with two fingers to zoom (anchored at the finger midpoint, which also pans as it moves) or drag with one finger to pan. Press Esc or click the mask to close. The close button is focused when opened, and focus is restored on close. Emits oas-preview (detail contains src).
document.body (portal) so position: fixed keeps working even when the component sits inside a transform/filter ancestor. While portaled, ::part(preview-*) cannot pierce from the host — customize via CSS variables instead.
## Gallery Preview
Set preview-src-list (a JSON array of URLs) to enter gallery mode: use the side arrows, the toolbar paging buttons, or ←→ keys to page through, with an "n/total" counter. If an image fails to load, a failure placeholder (reusing the error slot content) is shown instead of a blank stage.
With infinite, paging wraps around: "next" on the last image returns to the first, and "prev" on the first image jumps to the last.
The list shows the src thumbnail, while the preview loads the high-resolution original from preview-src (the download link points to the original as well).
The external button calls openPreview() to open; when preview-open is present it controls the open state — internal open/close (click / Esc / close button) reflects back to the attribute and emits oas-preview-change (detail { open }), and adding/removing the attribute drives the overlay as well (two-way sync).
With a template[slot="toolbar"], the template content is cloned into the preview overlay toolbar area, replacing the default button group (the original template stays in the light DOM; without a template the default toolbar remains). oas-toolbar-render is emitted on clone and on every open: use element (the toolbar container) and actions (the viewer commands) from the detail to wire custom buttons to viewer commands. The buttons above are wired — try them.
oas-toolbar-render is { element, actions }: element is the cloned toolbar container (bind button events on it; re-binding is idempotent); the actions command set is listed below (prev/next work in gallery mode and are no-ops in single-image mode):
| Command | Description |
| --- | --- |
| `zoomIn` / `zoomOut` | Zoom in / out one step (same transform state machine as the wheel and default buttons) |
| `rotateLeft` / `rotateRight` | Rotate 90° counter-clockwise / clockwise |
| `flipX` / `flipY` | Flip horizontally / vertically |
| `download` | Trigger a download of the current preview image |
| `close` | Close the preview overlay (equivalent to Esc / mask click) |
| `prev` / `next` | Previous / next gallery image (respects the `infinite` boundary, same as default paging) |
Host wiring example:
```js
el.addEventListener('oas-toolbar-render', (e) => {
const { element, actions } = e.detail
element.querySelector('#my-zoom-in').onclick = actions.zoomIn
})
```
The shared preview of oas-image-group supports this as well: place a template[slot="toolbar"] directly inside the group and it is forwarded to the shared overlay. Custom toolbar buttons receive token-based base styles (readable in light/dark) and participate in the Tab focus trap.
## Load Events
Load success → oas-load
Load failure → oas-error
The main image emits oas-load on success and oas-error on final failure (both details contain src); during a fallback retry no oas-error is emitted — it fires only when the fallback also fails (detail.src is the fallback URL).
slot="placeholder"
slot="error"
template[slot="placeholder"] / template[slot="error"] (or any element carrying the same slot attribute) is cloned into the corresponding placeholder area, taking precedence over the built-in text; a failed image inside a gallery preview reuses the error slot content as well.
The toolbar provides "Flip horizontal" and "Flip vertical", composed into the same transform state machine as zoom, rotate, and pan — they compose without interfering with each other.
After zooming in, press and drag on the preview image to pan (clamped to the visible bounds). Scroll the wheel inside the preview area to zoom (page scrolling is blocked). Zoom step and limits can be overridden with CSS variables (see the table below).
A grid of thumbnails: clicking any one opens the shared gallery starting from that image (opening index matches the thumbnail src against the list).
Put multiple oas-image elements inside oas-image-group and the container collects them into a shared gallery: clicking any image opens the preview from that image, and the side arrows / keyboard ←→ page through the whole set (n/total counter). A child's own preview click is taken over by the container as the shared gallery — no per-image preview-src-list needed.
Dynamically adding/removing children (or changing their src) syncs the gallery automatically; current optionally controls the current index — when present, clicks open at current and internal paging reflects back to the attribute; when absent, the attribute is not created and only oas-change is emitted (detail: { current, prev }, see the message feedback above); infinite is passed through to the shared preview.
--oas-image-group-gap.
### Preview Zoom CSS Variables
| CSS Variable | Default | Description |
| --- | --- | --- |
| `--oas-image-zoom-step` | `0.5` | Zoom in/out step (shared by toolbar buttons and the wheel) |
| `--oas-image-zoom-min` | `0.5` | Zoom lower bound |
| `--oas-image-zoom-max` | `3` | Zoom upper bound |
Override them on the host element or at the theme level, e.g. `style="--oas-image-zoom-max: 5"`.
## Explicit Dimensions and Referrer Policy
`width` / `height` set explicit dimensions: numbers are treated as px, and any CSS size string (e.g. `50%`) passes through as-is onto the inner `img` (the `max-width: 100%` responsive constraint is preserved); empty values clear the sizing back to auto layout. `referrerpolicy` passes through to the inner `img` to control the privacy policy (e.g. `no-referrer`); an empty value falls back to the browser default.