• Stars
    star
    1,527
  • Rank 30,669 (Top 0.7 %)
  • Language
    JavaScript
  • License
    BSD 2-Clause "Sim...
  • Created almost 9 years ago
  • Updated 9 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Easily add "zoom on hover" functionality to your site's images. Lightweight, no-dependency JavaScript.

This repository is no longer actively maintained.

See #703 for details.


imgix logo

Drift adds easy "zoom on hover" functionality to your site's images, all with lightweight, no-dependency JavaScript.

npm version Build Status npm License styled with prettier All Contributors FOSSA Status


Installation

  • NPM: npm install drift-zoom
  • Bower: bower install drift
  • Manual: Download and use dist/Drift.min.js or dist/Drift.js

If you're using the pre-built version of Drift, it will automatically make window.Drift available for your use when included on your page.

If you prefer to use require statements and a build tool like Browserify, here are a couple examples to help:

var Drift = require('drift-zoom');

new Drift(…);

If your project uses ES6, you can do the following instead:

import Drift from 'drift-zoom';

new Drift(…);

Basic Usage

Once you've installed Drift via one of the above methods, you're ready to get started. There are no dependencies, so you can just start making cool stuff. Check out the announcement blog post. Here's an example of a basic implementation:

<img src="https://assets.imgix.net/dog.png?w=400" data-zoom="https://assets.imgix.net/dog.png?w=1200">

<p>This is a simple description of the dog picture.</p>
new Drift(document.querySelector("img"), {
  paneContainer: document.querySelector("p")
});

Demo 💻💻💻

Take a peek at our Demo Site.

Options / Defaults

Here's an example of using Drift with a custom configuration. All of the listed options are displayed with their default value.

var options = {
	// Prefix for generated element class names (e.g. `my-ns` will
	// result in classes such as `my-ns-pane`. Default `drift-`
	// prefixed classes will always be added as well.
	namespace: null,
	// Whether the ZoomPane should show whitespace when near the edges.
	showWhitespaceAtEdges: false,
	// Whether the inline ZoomPane should stay inside
	// the bounds of its image.
	containInline: false,
	// How much to offset the ZoomPane from the
	// interaction point when inline.
	inlineOffsetX: 0,
	inlineOffsetY: 0,
	// A DOM element to append the inline ZoomPane to.
	inlineContainer: document.body,
	// Which trigger attribute to pull the ZoomPane image source from.
	sourceAttribute: 'data-zoom',
	// How much to magnify the trigger by in the ZoomPane.
	// (e.g., `zoomFactor: 3` will result in a 900 px wide ZoomPane image
	// if the trigger is displayed at 300 px wide)
	zoomFactor: 3,
	// A DOM element to append the non-inline ZoomPane to.
	// Required if `inlinePane !== true`.
	paneContainer: document.body,
	// When to switch to an inline ZoomPane. This can be a boolean or
	// an integer. If `true`, the ZoomPane will always be inline,
	// if `false`, it will switch to inline when `windowWidth <= inlinePane`
	inlinePane: 375,
	// If `true`, touch events will trigger the zoom, like mouse events.
	handleTouch: true,
	// If present (and a function), this will be called
	// whenever the ZoomPane is shown.
	onShow: null,
	// If present (and a function), this will be called
	// whenever the ZoomPane is hidden.
	onHide: null,
	// Add base styles to the page. See the "Theming"
	// section of README.md for more information.
	injectBaseStyles: true,
	// An optional number that determines how long to wait before
	// showing the ZoomPane because of a `mouseenter` event.
	hoverDelay: 0,
	// An optional number that determines how long to wait before
	// showing the ZoomPane because of a `touchstart` event.
	// Setting this to a reasonable amount will allow users to execute
	// scroll-gestures events on touch-enabled devices with the image as
	// a starting point
	touchDelay: 0,
	// If true, a bounding box will show the area currently being previewed
	// during mouse hover
	hoverBoundingBox: false,
	// If true, a bounding box will show the area currently being previewed
	// during touch events
	touchBoundingBox: false,
	// A DOM element to append the bounding box to.
	boundingBoxContainer: document.body,
	// If true, the events related to handleTouch use passive listeners in
	// order to improve performance for touch devices.
	passive: false,
};

new Drift(document.querySelector('img'), options);

API

Drift#disable

Disable your Drift instance. This will prevent your Drift instance from showing, but will not hide it if it's currently visible.

var drift = new Drift(document.querySelector("img"), {
  paneContainer: document.querySelector("p")
});

document.querySelector(".disable-button").addEventListener("click", function() {
  drift.disable();
});

Drift#enable

Enable your Drift instance.

var drift = new Drift(document.querySelector("img"), {
  paneContainer: document.querySelector("p")
});

document.querySelector(".enable-button").addEventListener("click", function() {
  drift.enable();
});

Drift#setZoomImageURL(imageURL)

Change the URL of the zoom image to the passed string. This only has a visible effect while your Drift is currently open. When opening, Drift always pulls the zoom image URL from the specified sourceAttribute. If you want to make a "permanent" change that will persist after the user leaves and re-enters your Drift trigger, you update its sourceAttribute as well (default data-zoom). For more information about this method, please see issue #42.

var triggerEl = document.querySelector("img");
var drift = new Drift(triggerEl, {
  paneContainer: document.querySelector("p")
});

var frames = ["https://mysite.com/frame1.jpg", "https://mysite.com/frame2.jpg", "https://mysite.com/frame3.jpg"];

var currentFrame = 0;

setInterval(function() {
  currentFrame++;

  if (currentFrame > frames.length - 1) {
    currentFrame = 0;
  }

  drift.setZoomImageURL(frames[currentFrame]);
  triggerEl.setAttribute("data-zoom", frames[currentFrame]);
}, 1200);

Theming

By default, Drift injects an extremely basic set of styles into the page. You will almost certainly want to extend these basic styles for a prettier, more usable experience that matches your site. There is an included basic theme that may meet your needs, or at least give a good example of how to build out your own custom styles. The namespace option can be used as a way to easily apply different themes to specific instances of Drift.

If you need to do something very out of the ordinary, or just prefer to include the default styles in CSS yourself, you can pass injectBaseStyles: false when instantiating a new instance of Drift. Please note that if you disable the included base styles, you will still need to provide an animation for .drift-window.drift-opening and .drift-window.drift-closing (this can be a "noop" style animation, as seen in the base styles source).

FAQs/Examples

In this section we answer common questions about Drift.

Disabling on Mobile

If you would like the touch events not to fire on mobile for one reason or another, these two solutions should work for you.

CSS Solution (Recommended)

This solution places a transparent element over the image on mobiles to block touch events. Replace 1024px in the media query with your mobile breakpoint.

.zoom-image {
	position: relative;
}

.zoom-image::before {
	content: "";
	position: absolute;
	top: 0;
	left: 0;
	right: 0;
	bottom: 0;
	background: transparent;
}

@media only screen and (min-width: 1024px) {
	.zoom-image::before {
		display: none;
	}
}

JS Solution

This solution creates and destroys the Drift instance when the browser size changes. It depends on the library responsive.js but can easily be altered to use vanilla JS.

const driftOptions = {
	paneContainer: paneContainer,
	inlinePane: false,
	handleTouch: false
};

const handleChange = () => {
	requestAnimationFrame(() => {
		if (Responsive.is('mobile') && !!window.productZoom) {
			window.productZoom.destroy();
		} else {
			window.productZoom = new Drift(img, driftOptions);
		}
	})
}

window.addEventListener('resize', handleChange);
window.addEventListener('load', handleChange);

Use Drift with Multiple Images on the Same Page

This code will iterate over all elements on your page with the class drift-img, and will instantiate Drift for each element. You can update the query selector and pane as you see fit.

const driftImgs = document.querySelectorAll('.drift-img');
const pane = document.querySelector('.drift-pane');
driftImgs.map(img => {
	new Drift(img, {
		paneContainer: pane,
		inlinePane: false
	});
});

Browser Support

We support the latest version of Google Chrome (which automatically updates whenever it detects that a new version of the browser is available). We also support the current and previous major releases of desktop Firefox, Internet Explorer, and Safari on a rolling basis. Mobile support is tested on the most recent minor version of the current and previous major release for the default browser on iOS and Android (e.g., iOS 9.2 and 8.4). Each time a new version is released, we begin supporting that version and stop supporting the third most recent version.

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Paul Straw

📖 💻 🚧

sherwinski

💻 📖 🚧

Frederick Fogerty

💻 📖 🚧

Jason Eberle

💻 📖 🚧

Luis H. Ball Jr.

🚧

This project follows the all-contributors specification. Contributions of any kind welcome!

Meta

Drift was made by imgix. It's licensed under the BSD 2-Clause license (see the license file for more info). Any contribution is absolutely welcome, but please review the contribution guidelines before getting started.

License

FOSSA Status

More Repositories

1

imgix.js

Responsive images in the browser, simplified
JavaScript
965
star
2

luminous

A simple, lightweight, no-dependencies JavaScript lightbox
JavaScript
771
star
3

react-imgix

React component to display imgix images
JavaScript
360
star
4

prometheus-am-executor

Execute command based on Prometheus alerts
Go
234
star
5

js-core

A JavaScript client library for generating image URLs with imgix
JavaScript
122
star
6

imgix-php

A PHP client library for generating URLs with imgix
PHP
111
star
7

imgix-rails

A gem for integrating imgix into Rails projects
Ruby
110
star
8

imgix-rb

A Ruby gem for generating image URLs with imgix
Ruby
76
star
9

jekyll-imgix

A plugin for integrating imgix into Jekyll sites
Ruby
51
star
10

motif

A simple Rails app to create responsive social images
HTML
41
star
11

imgix-url-params

Organized, machine-friendly documentation of imgix's URL parameters
39
star
12

imgix-python

A Python client library for generating URLs with imgix
Python
37
star
13

vue

A simple yet powerful integration between Vue and imgix
TypeScript
35
star
14

gatsby

A simple yet powerful integration between Gatsby and imgix
TypeScript
30
star
15

imgix-objc

Official imgix Objective-C client.
Objective-C
29
star
16

ember-cli-imgix

Easily add imgix functionality to your Ember application
JavaScript
26
star
17

imgix-swift

A Swift client library for generating URLs with imgix
Swift
25
star
18

magento

Browse, search, and insert image assets into your storefront quickly and easily via the imgix Image Manager.
JavaScript
21
star
19

imgix-emacs

An emacs major-mode for editing images via imgix.
Emacs Lisp
20
star
20

imgix-java

A Java client library for generating URLs with imgix
Java
19
star
21

django-imgix

Django module to provide imgix template tags and functions
Python
19
star
22

imgix-blueprint

Documentation for creating imgix libraries in different languages
18
star
23

imgix-statamic

An add-on for integrating imgix into Statamic sites
PHP
17
star
24

paperclip-imgix

Paperclip plugin to integrate with Imgix
Ruby
15
star
25

imgix-csharp

A C# client library for generating image URLs with imgix
C#
15
star
26

imgix-go

A Go client library for generating image URLs with imgix
Go
13
star
27

contentful

Browse, search, and add assets into your content quickly and easily via the imgix Asset Manager.
TypeScript
10
star
28

imgix-management-js

A Javascript library that wraps the imgix management API
JavaScript
7
star
29

typescript-imgix-url-params

TypeScript definitions of imgix's URL parameters
TypeScript
5
star
30

eddy

High-performance, maintenence-light, caching library and tools.
C
5
star
31

ix-video

An imgix video custom element that works anywhere
TypeScript
4
star
32

angular

A library for integrating imgix into Angular applications
TypeScript
4
star
33

fontmanager

Command line font manager for OS X
Objective-C
3
star
34

web-components

SDK web components shared across Frontend Frameworks - WIP
TypeScript
3
star
35

go-httpstring

fast http header string parser
Go
2
star
36

go-jobmanager

run subproc pools, on-demand grow and shrink, communicate with length-prefixed response, monitor RSS
Go
2
star
37

strapi-plugin-imgix

Strapi integration for imgix
TypeScript
2
star
38

renovate-config

A shareable Renovate bot configuration for all SDK repos
1
star
39

web-tools

Tools and configurations common to all imgix web projects
JavaScript
1
star
40

imgix-webfolder-router

A simple node.js router to allow multiple Base URLs for imgix Web Folders
JavaScript
1
star
41

nyt-example-app

Demos the imgix srcset API
HTML
1
star
42

sf-commerce-cloud

Use this integration to insert images from imgix's Image Manager into your Salesforce Commerce Cloud websites.
JavaScript
1
star
43

react-native-expo-example-app

Example Expo React Native application using @imgix/js-core to render a responsive image
JavaScript
1
star
44

shopify-integration-guide

Guide for integrating Shopify with imgix
1
star
45

web-tools-ds

Web-tools plugin and pipelines for reading in data assets in a variety of formats and storing them for use in templates
JavaScript
1
star