Skip to content
Latestv1.0.63

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.

Basic Usage

Placeholder and Load Failure ​

Customize placeholder content via placeholder and error slots.

Placeholder and Load Failure

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.

Lazy Load

Image Preview ​

Enable preview functionality via preview-src-list.

Image Preview

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.

Manual Preview Call

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.

Viewer.js Advanced Preview

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.

Use in Nuxt

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 ​

PropDescriptionTypeDefault
srcImage source URLstring''
fitHow the image fits its container, equivalent to native object-fit'' | 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'''
lazyWhether to enable lazy loadingbooleanfalse
preview-src-listSource list used by the built-in preview viewerstring[][]
z-indexPreview z-indexnumberundefined
initial-indexStart index of previewnumber0
close-on-press-escapeWhether pressing Esc closes previewbooleantrue
hide-on-click-modalWhether clicking the overlay closes previewbooleanfalse
infiniteWhether preview loops infinitelybooleantrue
zoom-rateZoom step used by the preview viewernumber1.2
show-progressWhether to show preview progress controlsbooleantrue
preview-teleportedWhether to teleport the preview container to bodybooleantrue
scroll-containerScroll container used for lazy loadingstring | HTMLElement | undefinedundefined
viewer-modePreview mode. Use 'viewerjs' when integrating Viewer.js behavior'default' | 'viewerjs''default'
viewer-optionsOptions forwarded to Viewer.js when viewer-mode="viewerjs"Record<string, unknown>{}
altNative img alt attributestringundefined
crossoriginNative img crossorigin attribute'' | 'anonymous' | 'use-credentials'undefined
loadingNative img loading attribute'eager' | 'lazy'undefined
theme-overridesComponent-level theme overridesComponentThemeVarsundefined

Events ​

Event NameDescriptionCallback Parameters
loadTriggered on image load success(event: Event) => void
errorTriggered on image load failure(event: Event | string) => void
switchTriggered on preview image switch(index: number) => void
showTriggered when preview is shown() => void
closeTriggered when preview is closed() => void

Slots ​

Slot NameDescription
placeholderPlaceholder when image is not loaded
errorContent 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 ​

PropDescriptionTypeDefault
url-listPreview image source liststring[][]
z-indexPreview z-indexnumber2000
initial-indexStart index of previewnumber0
infiniteWhether preview loops infinitelybooleantrue
hide-on-click-modalWhether clicking the overlay closes previewbooleanfalse
close-on-press-escapeWhether pressing Esc closes previewbooleantrue
zoom-rateZoom step used by the preview viewernumber1.2
show-progressWhether to show preview progress controlsbooleantrue
teleportedWhether to teleport the preview container to bodybooleantrue
viewer-modePreview mode'default' | 'viewerjs''default'
viewer-optionsViewer.js optionsRecord<string, unknown>{}

Events ​

Event NameDescriptionCallback Parameters
switchTriggered on image switch(index: number) => void
closeTriggered when preview closes() => void

Slots ​

This component does not expose component slots.

Image Viewer Expose ​

NameDescriptionType
prevSwitch to the previous image() => void
nextSwitch to the next image() => void
zoomInZoom in() => void
zoomOutZoom out() => void
rotateLeftRotate counterclockwise() => void
rotateRightRotate clockwise() => void
resetReset zoom and rotation state() => void

Theme Variables ​

YhImage supports themeOverrides. The component also provides the following dedicated CSS variables:

VariableDescriptionDefault
--yh-image-placeholder-bg-colorPlaceholder background colorvar(--yh-fill-color-light)
--yh-image-placeholder-text-colorPlaceholder text colorvar(--yh-text-color-placeholder)
--yh-image-error-bg-colorError area background colorvar(--yh-fill-color-extra-light)
--yh-image-error-text-colorError area text colorvar(--yh-text-color-placeholder)
--yh-image-viewer-mask-bg-colorPreview mask background colorvar(--yh-mask-color)
--yh-image-viewer-btn-bg-colorPreview controller button backgroundvar(--yh-text-color-regular)
--yh-image-viewer-btn-colorPreview controller button icon colorvar(--yh-color-white)
--yh-image-viewer-btn-hover-bg-colorPreview controller button hovervar(--yh-color-primary)

Type Exports ​

NameDescription
YhImagePropsProps type for YhImage
YhImageEmitsEmits type for YhImage
YhImageSlotsSlots type for YhImage
YhImageInstancePublic instance type for YhImage
YhImageViewerPropsProps type for YhImageViewer
YhImageViewerEmitsEmits type for YhImageViewer
YhImageViewerSlotsSlots type for YhImageViewer
YhImageViewerExposeExpose type for YhImageViewer
YhImageViewerInstancePublic instance type for YhImageViewer

Released under the MIT License.