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
YhImage and YhImageViewer can be used directly in Nuxt applications. During SSR, render the component normally and let lazy loading and preview behavior start on the client after hydration.
Supports auto-import and SSR placeholder rendering
SSR Notes:
- Supports placeholder rendering during SSR.
- Lazy loading starts observing on the client after hydration.
- Preview mode mounts the viewer on the client when it is opened.
- Works with Nuxt auto-import after registering the YH-UI module.
API
Props
| Prop | Description | Type | Default |
|---|---|---|---|
| src | Image source URL | string | '' |
| fit | How the image fits its container, equivalent to native object-fit | '' | 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | '' |
| lazy | Whether to enable lazy loading | boolean | false |
| preview-src-list | Source list used by the built-in preview viewer | string[] | [] |
| z-index | Preview z-index | number | undefined |
| initial-index | Start index of preview | number | 0 |
| close-on-press-escape | Whether pressing Esc closes preview | boolean | true |
| hide-on-click-modal | Whether clicking the overlay closes preview | boolean | false |
| infinite | Whether preview loops infinitely | boolean | true |
| zoom-rate | Zoom step used by the preview viewer | number | 1.2 |
| show-progress | Whether to show preview progress controls | boolean | true |
| preview-teleported | Whether to teleport the preview container to body | boolean | true |
| scroll-container | Scroll container used for lazy loading | string | HTMLElement | undefined | undefined |
| viewer-mode | Preview mode. Use 'viewerjs' when integrating Viewer.js behavior | 'default' | 'viewerjs' | 'default' |
| viewer-options | Options forwarded to Viewer.js when viewer-mode="viewerjs" | Record<string, unknown> | {} |
| alt | Native img alt attribute | string | undefined |
| crossorigin | Native img crossorigin attribute | '' | 'anonymous' | 'use-credentials' | undefined |
| loading | Native img loading attribute | 'eager' | 'lazy' | undefined |
| theme-overrides | Component-level theme overrides | ComponentThemeVars | undefined |
Events
| Event Name | Description | Callback Parameters |
|---|---|---|
| load | Triggered on image load success | (event: Event) => void |
| error | Triggered on image load failure | (event: Event | string) => void |
| switch | Triggered on preview image switch | (index: number) => void |
| show | Triggered when preview is shown | () => void |
| close | Triggered when preview is closed | () => void |
Slots
| Slot Name | Description |
|---|---|
| placeholder | Placeholder when image is not loaded |
| error | Content for load failure |
Expose
This component does not expose public instance methods or properties.
ImageViewer API
If you need to use the previewer independently, use yh-image-viewer.
Image Viewer Props
| Prop | Description | Type | Default |
|---|---|---|---|
| url-list | Preview image source list | string[] | [] |
| z-index | Preview z-index | number | 2000 |
| initial-index | Start index of preview | number | 0 |
| infinite | Whether preview loops infinitely | boolean | true |
| hide-on-click-modal | Whether clicking the overlay closes preview | boolean | false |
| close-on-press-escape | Whether pressing Esc closes preview | boolean | true |
| zoom-rate | Zoom step used by the preview viewer | number | 1.2 |
| show-progress | Whether to show preview progress controls | boolean | true |
| teleported | Whether to teleport the preview container to body | boolean | true |
| viewer-mode | Preview mode | 'default' | 'viewerjs' | 'default' |
| viewer-options | Viewer.js options | Record<string, unknown> | {} |
Events
| Event Name | Description | Callback Parameters |
|---|---|---|
| switch | Triggered on image switch | (index: number) => void |
| close | Triggered when preview closes | () => void |
Slots
This component does not expose component slots.
Image Viewer Expose
| Name | Description | Type |
|---|---|---|
| prev | Switch to the previous image | () => void |
| next | Switch to the next image | () => void |
| zoomIn | Zoom in | () => void |
| zoomOut | Zoom out | () => void |
| rotateLeft | Rotate counterclockwise | () => void |
| rotateRight | Rotate clockwise | () => void |
| reset | Reset zoom and rotation state | () => void |
Theme Variables
YhImage supports themeOverrides. The component also provides the following dedicated CSS variables:
| 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-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) |
Type Exports
| Name | Description |
|---|---|
YhImageProps | Props type for YhImage |
YhImageEmits | Emits type for YhImage |
YhImageSlots | Slots type for YhImage |
YhImageInstance | Public instance type for YhImage |
YhImageViewerProps | Props type for YhImageViewer |
YhImageViewerEmits | Emits type for YhImageViewer |
YhImageViewerSlots | Slots type for YhImageViewer |
YhImageViewerExpose | Expose type for YhImageViewer |
YhImageViewerInstance | Public instance type for YhImageViewer |