Qwik Adapter

The Qwik adapter provides hooks for implementing zoom image functionality in Qwik applications with resumable, serializable state.

Installation

npm install @zoom-image/qwik

Available Hooks

The Qwik adapter exports four hooks that correspond to different zoom behaviors:

useZoomImageWheel - Zoom with mouse wheel
useZoomImageHover - Zoom on hover with separate zoom target
useZoomImageMove - Zoom on mouse move
useZoomImageClick - Zoom on click

useZoomImageWheel

Enables zooming with mouse wheel/trackpad scrolling.

API

function useZoomImageWheel(): {
  createZoomImage: QRL<(...args: Parameters<typeof createZoomImageWheel>) => void>
  zoomImageState: ZoomImageWheelState
  setZoomImageState: QRL<(state: ZoomImageWheelStateUpdate) => void>
}

State

interface ZoomImageWheelState {
  currentZoom: number
  enable: boolean
  currentPositionX: number
  currentPositionY: number
  currentRotation: number
}

Example

import { component$, useSignal, useVisibleTask$ } from "@builder.io/qwik"
import { useZoomImageWheel } from "@zoom-image/qwik"

export default component$(() => {
  const imageContainerRef = useSignal<HTMLDivElement>()
  
  const {
    createZoomImage,
    zoomImageState,
    setZoomImageState
  } = useZoomImageWheel()
  
  useVisibleTask$(({ track }) => {
    track(() => imageContainerRef.value)
    
    if (imageContainerRef.value) {
      createZoomImage(imageContainerRef.value)
    }
  })
  
  return (
    <div>
      <p>Current zoom: {Math.round(zoomImageState.currentZoom * 100)}%</p>
      <p>Scroll inside the image to zoom</p>
      
      <div ref={imageContainerRef} class="h-[300px] w-[200px]">
        <img src="/image.jpg" alt="Zoomable image" class="h-full w-full" />
      </div>
      
      <div class="flex gap-2">
        <button
          onClick$={() => {
            setZoomImageState({
              currentZoom: zoomImageState.currentZoom + 0.5
            })
          }}
        >
          Zoom In
        </button>
        <button
          onClick$={() => {
            setZoomImageState({
              currentZoom: zoomImageState.currentZoom - 0.5
            })
          }}
        >
          Zoom Out
        </button>
        <button
          onClick$={() => {
            setZoomImageState({
              currentRotation: zoomImageState.currentRotation + 90
            })
          }}
        >
          Rotate
        </button>
      </div>
    </div>
  )
})

useZoomImageHover

Displays a zoomed version in a separate container when hovering over the image.

API

function useZoomImageHover(): {
  createZoomImage: QRL<(...args: Parameters<typeof createZoomImageHover>) => void>
  zoomImageState: ZoomImageHoverState
  setZoomImageState: QRL<(state: ZoomImageHoverStateUpdate) => void>
}

State

interface ZoomImageHoverState {
  enabled: boolean
  zoomedImgStatus: "idle" | "loading" | "loaded" | "error"
}

Example

import { component$, useSignal, useVisibleTask$ } from "@builder.io/qwik"
import { useZoomImageHover } from "@zoom-image/qwik"

export default component$(() => {
  const imageContainerRef = useSignal<HTMLDivElement>()
  const zoomTargetRef = useSignal<HTMLDivElement>()
  
  const { createZoomImage, zoomImageState } = useZoomImageHover()
  
  useVisibleTask$(({ track }) => {
    track(() => imageContainerRef.value)
    track(() => zoomTargetRef.value)
    
    if (imageContainerRef.value && zoomTargetRef.value) {
      createZoomImage(imageContainerRef.value, {
        zoomImageSource: "/image-large.jpg",
        customZoom: { width: 400, height: 600 },
        zoomTarget: zoomTargetRef.value,
        scale: 2
      })
    }
  })
  
  return (
    <div class="flex gap-4">
      <div ref={imageContainerRef} class="relative h-[300px] w-[200px]">
        <img src="/image-small.jpg" alt="Hover to zoom" class="h-full w-full" />
      </div>
      
      <div ref={zoomTargetRef} class="absolute left-[250px]"></div>
    </div>
  )
})

useZoomImageMove

Zooms the image as the mouse moves over it.

API

function useZoomImageMove(): {
  createZoomImage: QRL<(...args: Parameters<typeof createZoomImageMove>) => void>
  zoomImageState: ZoomImageMoveState
}

State

interface ZoomImageMoveState {
  zoomedImgStatus: "idle" | "loading" | "loaded" | "error"
}

Example

import { component$, useSignal, useVisibleTask$ } from "@builder.io/qwik"
import { useZoomImageMove } from "@zoom-image/qwik"

export default component$(() => {
  const imageContainerRef = useSignal<HTMLDivElement>()
  
  const { createZoomImage, zoomImageState } = useZoomImageMove()
  
  useVisibleTask$(({ track }) => {
    track(() => imageContainerRef.value)
    
    if (imageContainerRef.value) {
      createZoomImage(imageContainerRef.value, {
        zoomImageSource: "/image-large.jpg"
      })
    }
  })
  
  return (
    <div ref={imageContainerRef} class="relative h-[300px] w-[200px] overflow-hidden">
      <img src="/image.jpg" alt="Move mouse to zoom" class="h-full w-full" />
    </div>
  )
})

useZoomImageClick

Toggles zoom when clicking on the image.

API

function useZoomImageClick(): {
  createZoomImage: QRL<(...args: Parameters<typeof createZoomImageClick>) => void>
  zoomImageState: ZoomImageClickState
}

State

interface ZoomImageClickState {
  zoomedImgStatus: "idle" | "loading" | "loaded" | "error"
}

Example

import { component$, useSignal, useVisibleTask$ } from "@builder.io/qwik"
import { useZoomImageClick } from "@zoom-image/qwik"

export default component$(() => {
  const imageContainerRef = useSignal<HTMLDivElement>()
  
  const { createZoomImage, zoomImageState } = useZoomImageClick()
  
  useVisibleTask$(({ track }) => {
    track(() => imageContainerRef.value)
    
    if (imageContainerRef.value) {
      createZoomImage(imageContainerRef.value, {
        zoomImageSource: "/image-large.jpg"
      })
    }
  })
  
  return (
    <div ref={imageContainerRef} class="relative h-[300px] w-[200px] overflow-hidden cursor-pointer">
      <img src="/image.jpg" alt="Click to zoom" class="h-full w-full" />
    </div>
  )
})

Cleanup

All hooks automatically handle cleanup when the component unmounts using Qwik’s cleanup function in useVisibleTask$. The cleanup removes event listeners and frees resources.

useVisibleTask$(({ cleanup }) => {
  cleanup(() => {
    // Resources are freed automatically
  })
})

Qwik-Specific Patterns

Using $ for Event Handlers

Qwik requires the $ suffix for event handlers to enable lazy loading:

<button onClick$={() => {
  setZoomImageState({ currentZoom: 2 })
}}>Zoom</button>

Tracking Reactive Dependencies

Use track() in useVisibleTask$ to re-run effects when dependencies change:

useVisibleTask$(({ track }) => {
  track(() => zoomType.value)
  
  // Re-runs when zoomType changes
  if (zoomType.value === "wheel") {
    createZoomImageWheel(containerRef.value)
  }
})

Non-Serializable Values

The zoom instance is non-serializable and uses noSerialize() internally. The state itself is serializable and resumable.

Combining Multiple Zoom Types

import { component$, useSignal, useComputed$, useVisibleTask$ } from "@builder.io/qwik"
import {
  useZoomImageWheel,
  useZoomImageHover,
  useZoomImageMove,
  useZoomImageClick
} from "@zoom-image/qwik"

type Tab = {
  name: string
  current: boolean
  value: "wheel" | "hover" | "move" | "click"
}

export default component$(() => {
  const tabs = useSignal<Tab[]>([
    { name: "Wheel", current: true, value: "wheel" },
    { name: "Hover", current: false, value: "hover" },
    { name: "Move", current: false, value: "move" },
    { name: "Click", current: false, value: "click" }
  ])
  
  const imageWheelContainerRef = useSignal<HTMLDivElement>()
  const imageHoverContainerRef = useSignal<HTMLDivElement>()
  const imageMoveContainerRef = useSignal<HTMLDivElement>()
  const imageClickContainerRef = useSignal<HTMLDivElement>()
  const zoomTargetRef = useSignal<HTMLDivElement>()
  
  const { createZoomImage: createZoomImageWheel } = useZoomImageWheel()
  const { createZoomImage: createZoomImageHover } = useZoomImageHover()
  const { createZoomImage: createZoomImageMove } = useZoomImageMove()
  const { createZoomImage: createZoomImageClick } = useZoomImageClick()
  
  const zoomType = useComputed$(() => {
    return tabs.value.find(tab => tab.current)?.value || "wheel"
  })
  
  useVisibleTask$(({ track }) => {
    track(() => zoomType.value)
    
    if (zoomType.value === "wheel" && imageWheelContainerRef.value) {
      createZoomImageWheel(imageWheelContainerRef.value)
    }
    
    if (zoomType.value === "hover" && imageHoverContainerRef.value && zoomTargetRef.value) {
      createZoomImageHover(imageHoverContainerRef.value, {
        zoomImageSource: "/image-large.jpg",
        customZoom: { width: 300, height: 500 },
        zoomTarget: zoomTargetRef.value,
        scale: 2
      })
    }
    
    if (zoomType.value === "move" && imageMoveContainerRef.value) {
      createZoomImageMove(imageMoveContainerRef.value, {
        zoomImageSource: "/image-large.jpg"
      })
    }
    
    if (zoomType.value === "click" && imageClickContainerRef.value) {
      createZoomImageClick(imageClickContainerRef.value, {
        zoomImageSource: "/image-large.jpg"
      })
    }
  })
  
  return (
    <div>
      <nav class="flex gap-4 mb-4">
        {tabs.value.map((tab) => (
          <button
            key={tab.name}
            onClick$={() => {
              tabs.value = tabs.value.map(t => ({
                ...t,
                current: t.name === tab.name
              }))
            }}
            class={tab.current ? "active" : ""}
          >
            {tab.name}
          </button>
        ))}
      </nav>
      
      {zoomType.value === "wheel" && (
        <div ref={imageWheelContainerRef} class="h-[300px] w-[200px]">
          <img src="/image.jpg" alt="Wheel zoom" class="h-full w-full" />
        </div>
      )}
      
      {zoomType.value === "hover" && (
        <div class="flex gap-4">
          <div ref={imageHoverContainerRef} class="h-[300px] w-[200px]">
            <img src="/image.jpg" alt="Hover zoom" class="h-full w-full" />
          </div>
          <div ref={zoomTargetRef}></div>
        </div>
      )}
      
      {zoomType.value === "move" && (
        <div ref={imageMoveContainerRef} class="h-[300px] w-[200px] overflow-hidden">
          <img src="/image.jpg" alt="Move zoom" class="h-full w-full" />
        </div>
      )}
      
      {zoomType.value === "click" && (
        <div ref={imageClickContainerRef} class="h-[300px] w-[200px] overflow-hidden">
          <img src="/image.jpg" alt="Click zoom" class="h-full w-full" />
        </div>
      )}
    </div>
  )
})

TypeScript Support

The Qwik adapter is written in TypeScript and provides full type definitions. Import types from @zoom-image/core:

import type {
  ZoomImageWheelState,
  ZoomImageWheelStateUpdate,
  ZoomImageHoverState,
  ZoomImageHoverStateUpdate,
  ZoomImageMoveState,
  ZoomImageClickState
} from "@zoom-image/core"

createZoomImageWheel - Core wheel zoom function
createZoomImageHover - Core hover zoom function
createZoomImageMove - Core move zoom function
createZoomImageClick - Core click zoom function
React Adapter - React implementation
Vue Adapter - Vue implementation

Core API

Utilities

React Hooks

Vue Composables

Other Adapters

Types

Installation

Available Hooks

useZoomImageWheel

API

State

Example

useZoomImageHover

API

State

Example

useZoomImageMove

API

State

Example

useZoomImageClick

API

State

Example

Cleanup

Qwik-Specific Patterns

Using $ for Event Handlers

Tracking Reactive Dependencies

Non-Serializable Values

Combining Multiple Zoom Types

TypeScript Support

Core API

Utilities

React Hooks

Vue Composables

Other Adapters

Types

Documentation Index

​Installation

​Available Hooks

​useZoomImageWheel

​API

​State

​Example

​useZoomImageHover

​API

​State

​Example

​useZoomImageMove

​API

​State

​Example

​useZoomImageClick

​API

​State

​Example

​Cleanup

​Qwik-Specific Patterns

​Using $ for Event Handlers

​Tracking Reactive Dependencies

​Non-Serializable Values

​Combining Multiple Zoom Types

​TypeScript Support

​Related

Installation

Available Hooks

useZoomImageWheel

API

State

Example

useZoomImageHover

API

State

Example

useZoomImageMove

API

State

Example

useZoomImageClick

API

State

Example

Cleanup

Qwik-Specific Patterns

Using $ for Event Handlers

Tracking Reactive Dependencies

Non-Serializable Values

Combining Multiple Zoom Types

TypeScript Support

Related