Skip to content
Latestv1.0.63

Image Magnifier ​

Professional high-definition image magnification for product detail pages. Supports external/internal zoom, gallery mode, mouse-wheel dynamic scaling, smart positioning, progressive HD loading, minimap navigation, and fullscreen immersive preview.

Basic Usage ​

Standard external magnification — the zoom panel appears to the right by default.

External Mode

Inside Zoom ​

The zoom effect is rendered as a floating lens directly within the image. Perfect for compact layouts.

Embedded Lens Mode

Feature 1: Dynamic Wheel Zoom ​

Enable wheel-zoom to let users scroll the mouse wheel to dynamically adjust magnification in real time. A scale badge is automatically displayed in the top-left corner.

Mouse Wheel Dynamic Zoom

Feature 2: Smart Auto Positioning ​

Set position="auto" to let the component measure the remaining viewport space and automatically choose the best panel direction (right / left / inside).

Smart Auto Positioning

Feature 3: Progressive HD Loading ​

When zoom-src is still loading, an animated progress bar is shown at the bottom of the image. The preview switches seamlessly once the high-res image is ready.

Progressive HD Loading

Pass an images array to enable multi-image mode with built-in thumbnail navigation. Supports v-model for bidirectional index binding.

Gallery Mode

Feature 5: Minimap Navigation ​

Enable show-minimap to display a miniature overview of the full image in the bottom-right corner of the preview panel. A highlighted rectangle tracks your current viewing region.

Minimap Navigation

Feature 6: Click to Fullscreen ​

Enable click-to-fullscreen so that clicking the image opens an immersive fullscreen viewer. Press Esc or click the backdrop to close.

Fullscreen Immersive Preview

HD Sources & Customization ​

Specify a higher-resolution source via zoom-src. Customize offset, mask-color, and enable border/shadow.

Custom Configuration

Usage in Nuxt ​

Since the image magnifier involves mouse event monitoring and coordinate calculation, wrap the component with <client-only>.

Nuxt Integration

API ​

Props ​

PropertyDescriptionTypeDefault
srcMain image URLstring''
zoom-srcHD zoom image URL (falls back to src)string''
imagesImage gallery array, enables multi-image modeImageMagnifierImage[][]
model-value (v-model)Active image indexnumber0
scaleInitial zoom scale factornumber2
wheel-zoomEnable mouse-wheel dynamic zoombooleanfalse
min-scaleMinimum scale (wheel zoom)number1.2
max-scaleMaximum scale (wheel zoom)number5
scale-stepScale increment per wheel ticknumber0.3
widthContainer widthnumber | string'100%'
heightContainer heightnumber | string'auto'
positionZoom panel direction; auto for smart detection'right' | 'left' | 'inside' | 'auto''right'
offsetGap between container and panel (px)number10
mask-shapeLens shape'square' | 'circle''square'
mask-widthLens width (px)number150
mask-heightLens height (px)number150
mask-colorLens background colorstring'rgba(0, 0, 0, 0.3)'
show-minimapShow minimap navigation in the preview panelbooleanfalse
borderShow main image borderbooleanfalse
shadowShow main image shadowbooleanfalse
titleBottom hint textstring''
altImage alt attributestring''
click-to-fullscreenClick to enter fullscreen previewbooleanfalse
theme-overridesCSS variable overridesRecord<string, string>{}

Events ​

EventDescriptionParameters
enterFires when mouse enters the image—
leaveFires when mouse leaves the image—
zoom-startFires when zoom preview opens—
zoom-endFires when zoom preview closes—
scale-changeFires when wheel zoom changes the scale(scale: number)
image-changeFires when gallery image switches(index: number)
update:modelValuev-model update for gallery index(index: number)

Slots ​

SlotDescriptionScope
defaultReplace the default main <img> element—
titleCustomize the bottom title area—
close-iconCustomize the fullscreen close button icon—
fullscreenCustomize fullscreen content area{ src: string, alt: string }

ImageMagnifierImage Type ​

ts
interface ImageMagnifierImage {
  src: string
  zoomSrc?: string
  alt?: string
}

Exposed Methods & Properties ​

NameDescriptionType
visibleWhether the zoom preview is currently activeRef<boolean>
currentScaleCurrent zoom scaleRef<number>
currentIndexCurrent active image indexRef<number>
switchImageProgrammatically switch the active image(index: number) => void

Theme Variables ​

Override the following CSS custom properties via theme-overrides to customize the appearance:

VariableDescriptionDefault
--yh-magnifier-preview-borderPreview panel border colorvar(--yh-border-color-lighter)
--yh-magnifier-preview-shadowPreview panel box shadow0 8px 24px rgba(0,0,0,0.15)
--yh-magnifier-mask-bgLens overlay background colorrgba(0,0,0,0.2)
--yh-magnifier-mask-borderLens overlay border colorrgba(255,255,255,0.6)
--yh-magnifier-radiusBorder radiusvar(--yh-radius-base)
--yh-magnifier-loading-colorLoading progress bar colorvar(--yh-color-primary)
--yh-magnifier-gallery-active-borderGallery active thumbnail bordervar(--yh-color-primary)
--yh-magnifier-badge-bgScale badge backgroundrgba(0,0,0,0.55)
--yh-magnifier-badge-colorScale badge text color#fff
--yh-magnifier-minimap-sizeMinimap widget size80px
--yh-magnifier-fullscreen-bgFullscreen overlay backgroundrgba(0,0,0,0.88)
--yh-magnifier-title-bgTitle overlay backgroundrgba(0,0,0,0.5)

Type Exports ​

NameDescription
YhImageMagnifierPropsComponent props type
YhImageMagnifierEmitsComponent emits type
YhImageMagnifierSlotsComponent slots type
YhImageMagnifierExposeComponent expose type
YhImageMagnifierImageImage data type
YhImageMagnifierPositionPreview position union
YhImageMagnifierMaskShapeLens shape union
YhImageMagnifierInstanceComponent instance type

Released under the MIT License.