hoverzoom-js
Advanced tools
A lightweight, high-performance hover-to-zoom image magnifier plugin with zero dependencies
HoverZoom is a lightweight plugin built on vanilla JavaScript that allows users to zoom images on hover.
No dependencies, no jQuery, fully optimized for minimal download size and fast performance.
destroy() methodTested in:
The fastest way to get started:
<!DOCTYPE html>
<html>
<head>
<!-- CSS from CDN -->
<link
rel="stylesheet"
href="https://unpkg.com/hoverzoom-js@latest/dist/hoverzoom.min.css"
/>
</head>
<body>
<!-- Your image -->
<div class="hoverzoom">
<img class="hoverzoom-image" src="your-image.jpg" alt="Zoom image" />
</div>
<!-- JS from CDN -->
<script src="https://unpkg.com/hoverzoom-js@latest/dist/hoverzoom.umd.min.js"></script>
<script>
// Initialize
const hoverZoom = new HoverZoom();
hoverZoom.init();
</script>
</body>
</html>
Include the stylesheet in your <head>:
<link
rel="stylesheet"
href="https://unpkg.com/hoverzoom-js@latest/dist/hoverzoom.min.css"
/>
Include the script before closing <body>:
<script src="https://unpkg.com/hoverzoom-js@latest/dist/hoverzoom.umd.min.js"></script>
HTML Structure:
<!-- Basic usage -->
<div class="hoverzoom">
<img class="hoverzoom-image" src="image.jpg" alt="Zoom this image" />
</div>
<!-- With all options -->
<div class="hoverzoom">
<img class="hoverzoom-image" src="thumbnail.jpg"
data-large-image="full-size.jpg"
<!-- Optional: use different image for zoom -->
data-type="outside"
<!-- 'outside' or 'inside' -->
data-position="right"
<!-- 'right' or 'bottom' (for outside type) -->
data-blur="true"
<!-- Optional: blur effect -->
data-grayscale="true"
<!-- Optional: grayscale effect -->
alt="Product image" >
</div>
Initialize:
<script>
// Default options
const hoverZoom = new HoverZoom();
hoverZoom.init();
// Or with custom options
const hoverZoom = new HoverZoom({
position: 'right', // 'right' | 'bottom' (for outside type)
type: 'outside', // 'outside' | 'inside'
blur: false, // apply blur filter on hover
grayscale: false, // apply grayscale filter on hover
throttleDelay: 16, // mousemove throttle (ms) - 16ms = ~60fps
});
hoverZoom.init();
// Cleanup when done (e.g., SPA route change)
// hoverZoom.destroy();
</script>
Install:
# pnpm (recommended)
pnpm add hoverzoom-js
# npm
npm install hoverzoom-js
# yarn
yarn add hoverzoom-js
JavaScript/TypeScript Usage:
// ES Module (TypeScript or modern JS)
import HoverZoom from 'hoverzoom-js';
import 'hoverzoom-js/style.css';
const hoverZoom = new HoverZoom({
position: 'right',
type: 'outside',
blur: false,
grayscale: false,
});
// Initialize all elements with 'hoverzoom' class
hoverZoom.init();
// Cleanup when component unmounts (important for SPAs)
// hoverZoom.destroy();
React Example:
import { useEffect } from 'react';
import HoverZoom from 'hoverzoom-js';
import 'hoverzoom-js/style.css';
function ProductImage() {
useEffect(() => {
const hoverZoom = new HoverZoom();
hoverZoom.init();
// Cleanup on unmount
return () => hoverZoom.destroy();
}, []);
return (
<div className="hoverzoom">
<img className="hoverzoom-image" src="product.jpg" alt="Product" />
</div>
);
}
Vue Example:
<template>
<div class="hoverzoom">
<img class="hoverzoom-image" src="product.jpg" alt="Product" />
</div>
</template>
<script setup>
import { onMounted, onUnmounted } from 'vue';
import HoverZoom from 'hoverzoom-js';
import 'hoverzoom-js/style.css';
let hoverZoom;
onMounted(() => {
hoverZoom = new HoverZoom();
hoverZoom.init();
});
onUnmounted(() => {
hoverZoom?.destroy();
});
</script>
| Option | Type | Default | Description |
|---|---|---|---|
| position | string | "right" | Position of the zoomed image (right or bottom) |
| type | string | "outside" | Magnifier type (inside or outside) |
| blur | boolean | false | Apply blur filter to the original image |
| grayscale | boolean | false | Apply grayscale filter to the original image |
| throttleDelay | number | 16 | Mousemove throttle delay in ms (16ms = ~60fps) |
| classNames | object | {...} | Custom CSS class names for container, image, elements |
<div class="hoverzoom">
<img
class="hoverzoom-image"
src="small.jpg"
data-large-image="large.jpg"
data-type="outside"
data-position="right"
data-blur="true"
data-grayscale="false"
/>
</div>
Zoom not working?
hoverzoom class, image with hoverzoom-image classhoverZoom.init() after adding elements dynamicallydestroy() on unmount to prevent memory leaksImage not loading?
data-large-image path is correct (relative to HTML file or absolute URL)TypeScript errors?
import HoverZoom from "hoverzoom-js"We β€οΈ contributions!
git checkout -b feature/amazing-feature
git commit -m "Add amazing feature"
git push origin feature/amazing-feature
src/HoverZoom.ts)pnpm run build to compile TypeScript and test changespnpm run test:allβΈ»
HoverZoom is optimized for maximum performance:
translate3d for hardware-accelerated transforms# Unit tests (Jest)
pnpm test
pnpm run test:coverage # With coverage report
# E2E tests (Playwright)
pnpm run test:e2e
pnpm run test:e2e:ui # With UI mode
# All tests
pnpm run test:all
See TESTING.md for detailed testing documentation.
HoverZoom is built with accessibility in mind and supports:
See SCREEN_READER_TESTING.md for detailed accessibility testing guide.
# Build for production (compiles TypeScript)
pnpm run build:all
# Verify package contents
pnpm run verify
# Deploy to npm (automated)
pnpm run deploy
See DEPLOYMENT.md for complete deployment guide.
The project is written in TypeScript for better type safety and developer experience:
src/HoverZoom.ts (TypeScript)dist/*.js (ES Module & UMD formats)# Install dependencies
pnpm install
# Development workflow
pnpm run dev # Build + start dev server
pnpm run build # Compile TypeScript + build all
pnpm run test:watch # Run tests in watch mode
See BUILD_WORKFLOW.md for detailed build documentation.
MIT License
Submit via GitHub Issues.
βΈ»
Made with β€οΈ for building a lightweight, high-performance image zoom plugin.
FAQs
A lightweight, high-performance hover-to-zoom image magnifier plugin with zero dependencies
The npm package hoverzoom-js receives a total of 15 weekly downloads. As such, hoverzoom-js popularity was classified as not popular.
We found that hoverzoom-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Β It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Socket detected malicious node-ipc versions with obfuscated stealer/backdoor behavior in a developing npm supply chain attack.
Security News
TeamPCP and BreachForums are promoting a Shai-Hulud supply chain attack contest with a $1,000 prize for the biggest package compromise.
Security News
Packagist urges PHP projects to update Composer after a GitHub token format change exposed some GitHub Actions tokens in CI logs.