简体中文 | English
A lightweight pure JavaScript image preview library with no dependencies, ready to use out of the box.
- 🚀 Lightweight: No external dependencies, pure JavaScript implementation
- 📱 Responsive: Perfect for both PC and mobile devices
- 🎨 Beautiful: Modern interface design
- ⚡ Fast: High-performance image loading and preview
- 🔧 Easy: One line of code integration
Recommended via CDN:
<script src="https://cdn.jsdelivr.net/gh/inklife/pixelvoyager/pixelvoyager.js"></script>Or include locally:
<script src="pixelvoyager.js"></script>Simply wrap your images with <a> tags that have the pixel-voyager-link class, and the library will automatically register them when the page loads.
<!DOCTYPE html>
<html>
<head>
<title>PixelVoyager Example</title>
</head>
<body>
<!-- Wrap your images with <a> tags that have the "pixel-voyager-link" class -->
<!-- href is the image for fullscreen viewing, img src is the thumbnail displayed on page -->
<a href="high-res-image.jpg" class="pixel-voyager-link">
<img src="high-res-image-thumb.jpg" alt="Example Image">
</a>
<a href="another-high-res-image.jpg" class="pixel-voyager-link">
<img src="another-high-res-image-thumb.jpg" alt="Another Image">
</a>
<!-- Include the script via CDN (recommended) -->
<script src="https://cdn.jsdelivr.net/gh/inklife/pixelvoyager/pixelvoyager.js"></script>
</body>
</html>You can also call the API directly:
// Preview a single image
PixelVoyager.openImage('https://example.com/image.jpg');<!DOCTYPE html>
<html>
<head>
<title>PixelVoyager Example</title>
</head>
<body>
<div class="gallery">
<!-- href is the image for fullscreen viewing, img src is the thumbnail displayed on page -->
<a href="high-res-image1.jpg" class="pixel-voyager-link">
<img src="high-res-image1-thumb.jpg" alt="Image 1">
</a>
<a href="high-res-image2.jpg" class="pixel-voyager-link">
<img src="high-res-image2-thumb.jpg" alt="Image 2">
</a>
<a href="high-res-image3.jpg" class="pixel-voyager-link">
<img src="high-res-image3-thumb.jpg" alt="Image 3">
</a>
</div>
<script src="https://cdn.jsdelivr.net/gh/inklife/pixelvoyager/pixelvoyager.js"></script>
<!-- That's it! No additional JavaScript needed -->
</body>
</html><!DOCTYPE html>
<html>
<head>
<title>PixelVoyager Example</title>
</head>
<body>
<img src="demo.jpg" class="preview-image" alt="Example Image">
<script src="https://cdn.jsdelivr.net/gh/inklife/pixelvoyager/pixelvoyager.js"></script>
<script>
document.querySelectorAll('.preview-image').forEach(img => {
img.addEventListener('click', function() {
PixelVoyager.openImage(this.src);
});
});
</script>
</body>
</html>Check the html/pixelvoyager-minimal_en.html file for a complete integration example.
The simplest way to use PixelVoyager is through HTML structure registration. Just wrap your images with <a> tags that have the pixel-voyager-link class:
<a href="high-res-image.jpg" class="pixel-voyager-link">
<img src="high-res-image-thumb.jpg" alt="Image description">
</a>Requirements:
- Wrap
<img>tags with<a>tags - The
<a>tag must have the classpixel-voyager-link - The
hrefattribute should contain the full-size image URL (this is the image shown in fullscreen) - The
<img>tag inside should use a thumbnail or compressed version (this is the small image shown on the page)
Advantages:
- ✅ Zero JavaScript configuration required
- ✅ SEO-friendly semantic HTML structure
- ✅ Works immediately after including the script
- ✅ Graceful degradation (links work even without JavaScript)
- ✅ Auto-handles CSS styling to prevent whitespace issues
Preview a single image programmatically
Parameters:
url(String): Image URL
Example:
PixelVoyager.openImage('https://example.com/image.jpg');PixelVoyager provides rich configuration options to customize the user experience. You can pass configurations in the following ways:
You can configure the global instance using the configure method:
// Apply custom settings to the single global instance
PixelVoyager.configure({
zoomMode: 'center',
cornerColor: 'rgba(0, 128, 0, 0.8)',
blockingDelay: 500
});Important Notes for HTML Structure Registration:
- ✅ Configuration works: The updated version supports passing configuration options to HTML structure registration
- ✅ Global instance: All HTML structure links will use the same configured global instance
- ✅ Early configuration: Configure before DOM loads for best results
- ✅ Runtime configuration: Use
PixelVoyager.configure()to change settings dynamically - ✅ Visual feedback: You can see the corner indicators change color when configuration is applied
Method: Use Configuration with HTML Structure Registration
<script src="https://cdn.jsdelivr.net/gh/inklife/pixelvoyager/pixelvoyager.js"></script>
<script>
// Use the configure method (recommended)
PixelVoyager.configure({
zoomMode: 'center',
borderColor: 'rgba(255, 0, 0, 0.5)'
});
</script>| Option | Type | Default | Description |
|---|---|---|---|
zoomMode |
String | 'cursor' |
Zoom mode: 'cursor' - zoom centered on cursor, 'center' - zoom centered on canvas |
cornerColor |
String | 'rgba(64, 158, 255, 0.6)' |
Corner indicator color |
moveThreshold |
Number | 1 |
Movement threshold (pixels) for detecting drag start |
blockingDelay |
Number | 1000 |
Delay time (ms) to block click-to-close after drag ends |
checkInterval |
Number | 15 |
Mouse movement detection interval (ms) |
Cursor-centered zoom (zoomMode: 'cursor') - Default mode
- When zooming with mouse wheel, cursor always points to the same pixel on the image
- When double-clicking to zoom, zooms centered on the click position
- Suitable for precise detail viewing
Canvas-centered zoom (zoomMode: 'center')
- Always zooms relative to the canvas center
- Traditional zoom behavior
- Suitable for quick image browsing
// Create a configuration with center zoom and custom corner color
const voyager = new PixelVoyager({
zoomMode: 'center', // Use center zoom mode
cornerColor: 'rgba(255, 0, 0, 0.8)', // Custom corner color (red)
moveThreshold: 5, // Increase drag trigger threshold
blockingDelay: 500 // Reduce delay after drag
});
// Use the configured instance
voyager.openImage('https://example.com/image.jpg');// Vue 2/3 Component Example
export default {
data() {
return {
images: [
{ id: 1, thumbnail: 'thumb1.jpg', fullSize: 'image1.jpg' },
{ id: 2, thumbnail: 'thumb2.jpg', fullSize: 'image2.jpg' }
]
}
},
methods: {
openImagePreview(imageUrl) {
PixelVoyager.openImage(imageUrl);
}
},
template: `
<div class="gallery">
<img
v-for="(image, index) in images"
:key="image.id"
:src="image.thumbnail"
@click="openImagePreview(image.fullSize)"
class="preview-image"
:alt="'Image ' + (index + 1)"
/>
</div>
`
}import React from 'react';
function ImageGallery({ images }) {
const handleImageClick = (imageUrl) => {
PixelVoyager.openImage(imageUrl);
};
return (
<div className="gallery">
{images.map((image, index) => (
<img
key={image.id}
src={image.thumbnail}
onClick={() => handleImageClick(image.fullSize)}
className="preview-image"
alt={`Image ${index + 1}`}
/>
))}
</div>
);
}
// Usage
const images = [
{ id: 1, thumbnail: 'thumb1.jpg', fullSize: 'image1.jpg' },
{ id: 2, thumbnail: 'thumb2.jpg', fullSize: 'image2.jpg' }
];
function App() {
return <ImageGallery images={images} />;
}ESC- Close preview+/=- Zoom in-- Zoom out0- Reset view
- Chrome (Recommended)
- Firefox
- Safari
- Edge
MIT License
Issues and Pull Requests are welcome to improve this project.
- Initial release
- Support single image preview
- Responsive design
- Keyboard shortcuts support