hana-img-viewer

A lightweight and elegant image previewer for Vue 3 with smooth FLIP animations and touch gesture support.

Features

• FLIP Animation: Smooth transition from thumbnail to preview using the FLIP animation technique
• Touch Gestures: Drag, pan, and pinch-to-zoom with natural physics
• Mouse Support: Wheel zoom (anchored at cursor position), drag to pan, double-click to zoom
• Keyboard Support: Press ESC to close preview
• TypeScript: Full type safety with complete type definitions
• SSR Friendly: Works seamlessly with server-side rendering
• Lightweight: Only ~5KB gzipped
• Flexible Styling: Style the thumbnail container and image separately
• Vue 3 Composition API: Built with modern Vue 3 patterns

Installation

# pnpm (recommended)
pnpm add hana-img-viewer

# npm
npm install hana-img-viewer

# yarn
yarn add hana-img-viewer

Basic Usage

Partial Import

Import the component where you need it:

<script setup lang="ts">
import { HanaImgViewer } from 'hana-img-viewer'
</script>

<template>
  <HanaImgViewer src="/path/to/image.jpg" alt="Image description" />
</template>

Global Registration

Register globally in your main.ts:

import HanaImgViewer from 'hana-img-viewer'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
app.use(HanaImgViewer)
app.mount('#app')

Then use in any component:

<template>
  <hana-img-viewer src="/path/to/image.jpg" alt="Image description" />
</template>

API Reference

Props

| Prop | Type | Default | Description | | ---- | ---- | ------- | ----------- | | src | string | - | Required. Image URL. | | alt | string | '' | Alternative text for the image. | | previewSrc | string | - | High-resolution image URL for preview (defaults to src). | | containerClass | HTMLAttributes['class'] | - | Extra class for the thumbnail container. | | containerStyle | StyleValue | - | Extra style for the thumbnail container. | | thumbnailClass | HTMLAttributes['class'] | - | Extra class for the thumbnail image. | | thumbnailStyle | StyleValue | - | Extra style for the thumbnail image. | | duration | number | 300 | Animation duration in milliseconds. | | easing | string | 'cubic-bezier(0.4, 0, 0.2, 1)' | Animation easing function. | | maskColor | string | '#000' | Mask background color. | | maskOpacity | number | 0.3 | Mask opacity (0-1). | | zIndex | number | 9999 | Preview layer z-index. | | minZoom | number | 0.5 | Minimum zoom level. | | maxZoom | number | 10 | Maximum zoom level. | | zoomStep | number | 0.5 | Zoom increment per step. | | doubleClickZoom | number | 2 | Target zoom level on double-click. | | wheelZoomRatio | number | 1 | Wheel zoom sensitivity multiplier. | | enableZoom | boolean | true | Enable zoom functionality. | | enableDrag | boolean | true | Enable drag to pan. | | enablePinch | boolean | true | Enable pinch-to-zoom on touch devices. | | enableDoubleClick | boolean | true | Enable double-click to zoom. | | enableKeyboard | boolean | true | Enable keyboard controls (ESC to close). | | closeOnMaskClick | boolean | true | Close preview when clicking the mask. |

v-model Bindings

| Binding | Type | Description | | ------- | ---- | ----------- | | v-model:open | boolean | Controls preview open/close state. | | v-model:zoom | number | Controls current zoom level. |

Events

| Event | Payload | Description | | ----- | ------- | ----------- | | open | - | Emitted when preview opens. | | close | - | Emitted when preview closes. | | zoomChange | number | Emitted when zoom level changes. | | load | Event | Emitted when image loads successfully. | | error | Event | Emitted when image fails to load. |

Slots

| Slot | Props | Description | | ---- | ----- | ----------- | | thumbnail | { open: () => void } | Custom thumbnail content. | | loading | - | Custom loading state. | | error | - | Custom error state. | | toolbar | { zoom, zoomIn, zoomOut, reset, close, canZoomIn, canZoomOut } | Custom toolbar. |

Exposed Methods & State

Access via template ref:

<script setup lang="ts">
import { ref } from 'vue'

const viewerRef = ref()

// Open programmatically
viewerRef.value?.open()

// Close programmatically
viewerRef.value?.close()

// Zoom controls
viewerRef.value?.zoomIn()
viewerRef.value?.zoomOut()
viewerRef.value?.setZoom(2)
viewerRef.value?.resetZoom()
</script>

<template>
  <HanaImgViewer ref="viewerRef" src="/image.jpg" />
</template>

Exposed State:

• isOpen - Preview open state
• isAnimating - Animation state
• zoom - Current zoom level
• transform - Current transform state
• loadState - Image load state ('idle' | 'loading' | 'loaded' | 'error')
• canZoomIn - Whether can zoom in
• canZoomOut - Whether can zoom out
• isDragging - Drag state
• isPinching - Pinch state

Exposed Methods:

• open() - Open preview
• close() - Close preview
• zoomIn() - Zoom in
• zoomOut() - Zoom out
• setZoom(level) - Set zoom level
• resetZoom() - Reset zoom to initial
• resetTransform() - Reset all transforms

Advanced Usage

Controlled Mode

<script setup lang="ts">
import { ref } from 'vue'

const isOpen = ref(false)
const zoom = ref(1)
</script>

<template>
  <button @click="isOpen = true">
    Open Preview
  </button>
  <p>Current zoom: {{ zoom.toFixed(2) }}</p>

  <HanaImgViewer
    v-model:open="isOpen"
    v-model:zoom="zoom"
    src="/image.jpg"
  />
</template>

Custom Thumbnail

<template>
  <HanaImgViewer src="/high-res.jpg">
    <template #thumbnail="{ open }">
      <div class="custom-thumbnail" @click="open">
        <img src="/thumbnail.jpg" alt="Thumbnail">
        <span>Click to preview</span>
      </div>
    </template>
  </HanaImgViewer>
</template>

Thumbnail Styling

<template>
  <HanaImgViewer
    src="/image.jpg"
    container-class="inline-block overflow-hidden rounded-2xl"
    :container-style="{ width: '240px', aspectRatio: '4 / 3' }"
    thumbnail-class="transition-transform duration-300"
    :thumbnail-style="{ width: '100%', height: '100%', objectFit: 'cover' }"
  />
</template>

Custom Toolbar

<template>
  <HanaImgViewer src="/image.jpg">
    <template #toolbar="{ zoom, zoomIn, zoomOut, reset, close, canZoomIn, canZoomOut }">
      <div class="toolbar">
        <button :disabled="!canZoomOut" @click="zoomOut">
          -
        </button>
        <span>{{ (zoom * 100).toFixed(0) }}%</span>
        <button :disabled="!canZoomIn" @click="zoomIn">
          +
        </button>
        <button @click="reset">
          Reset
        </button>
        <button @click="close">
          Close
        </button>
      </div>
    </template>
  </HanaImgViewer>
</template>

Using Composables Directly

For advanced use cases, you can use the composables directly:

import {
  useControllable,
  useFLIP,
  useGesture,
  useScrollLock,
  useTransform,
  useZoom,
} from 'hana-img-viewer'

// Example: Create custom preview logic
const { zoom, zoomIn, zoomOut, setZoom } = useZoom({
  minZoom: 0.5,
  maxZoom: 5,
  step: 0.25,
})

const { transform, zoomAt, pan, reset } = useTransform()

const { lock, unlock } = useScrollLock()

TypeScript

Full TypeScript support is included:

import type {
  ImagePreviewEmits,
  ImagePreviewProps,
  Point,
  Transform,
} from 'hana-img-viewer'

Browser Support

• Chrome >= 84
• Firefox >= 75
• Safari >= 13.1
• Edge >= 84

Requires Web Animations API support.

License

MIT