Image
Displays image resources, with an optional built-in preview feature.
Basic Usage
Basic image
Fit Mode
object-fit variants
cover (crop to fill)
contain (fit fully)
Set object-fit via fit, then fix the image container size with ::part(image) to achieve the crop effect.
Placeholder and Fallback
Loading placeholder
With placeholder, a light-gray placeholder is shown until the image finishes loading, then it switches to the image.
Load failure fallback
Default failure placeholder
Custom fallback image
When the image fails to load, a "图片加载失败" placeholder is shown by default; the fallback attribute can specify a fallback image URL, and if the fallback also fails, it falls back to the placeholder text.
Lazy Loading
Lazy-loading long list (loads image by image while scrolling)
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).
Preview
Click to preview (built-in overlay)
Click the image to open a full-screen preview overlay: the toolbar supports zoom in / out, rotate, and download; 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).
API
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
alt | Alternative text | — | — |
fallback | Fallback image URL to switch to on load failure; when not set, shows the "图片加载失败" placeholder | string | — |
fit | object-fit value | string | — |
lazy | Lazy load: the image starts loading only when it enters the viewport (IntersectionObserver); loads immediately when already in the viewport; falls back to eager loading when unsupported | boolean | — |
placeholder | Show a light gray placeholder before the image finishes loading | boolean | — |
preview | Enable built-in preview: click to zoom + zoom/rotate/download + Esc to close + focus trap | boolean | — |
src | Image URL | string | — |
Events
| Event | Description |
|---|---|
oas-preview | Preview overlay opened, detail: { src }; closing the overlay does not emit an event |