Image
Image container with lazy loading, custom placeholder, load failure, and image preview support, while retaining original img characteristics.
Basic Usage
The fit attribute determines how the image adapts to the container, same as native object-fit.
Placeholder and Load Failure
Customize placeholder content via placeholder and error slots.
Lazy Load
TIP
Browser-native loading attribute. You can try replacing lazy="true" with loading="lazy".
If the current browser supports native image lazy loading, native capabilities are prioritized; otherwise, scroll listening will be used to achieve the same effect.
Enable lazy loading via lazy, so images load only when scrolled into view. You can set the scroll container via scroll-container; if undefined, it defaults to the nearest parent element with overflow set to auto or scroll.
Image Preview
Enable preview functionality via preview-src-list.
Manual Preview Call
Manually invoke the preview via the yh-image-viewer component. This is useful when you don't want to show thumbnails but want to trigger a preview on clicking an element (like a button or link). Manual calls for viewerjs mode are also supported.
Viewer.js Preview (Extension)
When the built-in previewer isn't enough, switch to the more powerful viewerjs mode. It supports advanced features like slideshows, fullscreen, flipping, and thumbnail navigation.
Use in Nuxt
The Image component fully supports Nuxt 3 SSR mode. We have fully considered server-client compatibility in its implementation of lazy loading and previewing.
Supports auto-import and SSR placeholder rendering
SSR Notes:
- ✅ Supports server-side placeholder rendering (Placeholder Slot).
- ✅ Lazy loading starts listening automatically after client-side activation.
- ✅ Previewer component uses Teleport to mount to body on the client.
- ✅ Perfectly compatible with Nuxt auto-import mechanism.
API
Props
| Prop | Description | Type | Default |
|---|---|---|---|
| src | Image source address | string | — |
| fit | How image fits container, same as native object-fit | 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | — |
| lazy | Whether to enable lazy loading | boolean | false |
| preview-src-list | Preview list | string[] | [] |
| z-index | Preview z-index | number | 2000 |
| initial-index | Start index of preview | number | 0 |
| close-on-press-escape | Close preview via ESC | boolean | true |
| hide-on-click-modal | Close preview via clicking mask | boolean | false |
| infinite | Whether to loop preview | boolean | true |
| zoom-rate | Preview zoom rate | number | 1.2 |
| show-progress | Show toolbar in preview mode | boolean | true |
| preview-teleported | Teleport preview container to body | boolean | true |
| scroll-container | Scroll container for lazy loading | string | HTMLElement | — |
| viewer-mode | Preview mode: 'default' (built-in), 'viewerjs' (external) | 'default' | 'viewerjs' | 'default' |
| viewer-options | Options passed to viewerjs | object | {} |
| alt | Native alt attribute | string | — |
| crossorigin | Native crossorigin attribute | string | — |
Events
| Event Name | Description | Callback Parameters |
|---|---|---|
| load | Triggered on image load success | (event: Event) => void |
| error | Triggered on image load failure | (event: Event) => void |
| switch | Triggered on preview image switch | (index: number) => void |
| show | Triggered when preview is shown | — |
| close | Triggered when preview is closed | — |
Slots
| Slot Name | Description |
|---|---|
| placeholder | Placeholder when image is not loaded |
| error | Content for load failure |
ImageViewer API
If you need to use the previewer independently, use yh-image-viewer.
ImageViewer Props
| Prop | Description | Type | Default |
|---|---|---|---|
| url-list | Preview image source list | string[] | [] |
| z-index | Preview z-index | number | 2000 |
| index | Start index of preview | number | 0 |
| infinite | Whether to loop preview | boolean | true |
| hide-on-click-modal | Close preview via clicking mask | boolean | false |
| close-on-press-escape | Close preview via ESC | boolean | true |
| zoom-rate | Preview zoom rate | number | 1.2 |
| show-progress | Whether to show toolbar | boolean | true |
| teleported | Whether to teleport to body | boolean | true |
| viewer-mode | Preview mode | 'default' | 'viewerjs' | 'default' |
| viewer-options | Viewer.js options | object | {} |
ImageViewer Events
| Event Name | Description | Callback Parameters |
|---|---|---|
| switch | Triggered on image switch | (index: number) => void |
| close | Triggered when preview closed | — |
Theme Variables
Customizes local styles via CSS variables. All colors are interfaced with the global theme and support dark mode:
| Variable | Description | Default |
|---|---|---|
--yh-image-placeholder-bg-color | Placeholder background color | var(--yh-fill-color-light) |
--yh-image-placeholder-text-color | Placeholder text color | var(--yh-text-color-placeholder) |
--yh-image-error-bg-color | Error area background color | var(--yh-fill-color-extra-light) |
--yh-image-error-text-color | Error area text color | var(--yh-text-color-placeholder) |
--yh-image-border-radius | Image border radius | var(--yh-radius-md) |
--yh-image-viewer-mask-bg-color | Preview mask background color | var(--yh-mask-color) |
--yh-image-viewer-btn-bg-color | Preview controller button background | var(--yh-text-color-regular) |
--yh-image-viewer-btn-color | Preview controller button icon color | var(--yh-color-white) |
--yh-image-viewer-btn-hover-bg-color | Preview controller button hover | var(--yh-color-primary) |