ClickSave: Building an Image Download Extension

Contents
  1. The Image-Saving Problem
  2. The First Version
  3. Finding the Original Image
  4. Designing the Download Button
  5. From Single to Batch Downloads
  6. Code Structure and Refactoring
  7. Maintaining Support Across Sites
  8. Next Steps
  9. From Practice Project to Store Release

Felix and I developed ClickSave, a Chrome extension for downloading images from web pages. It began with a repetitive task while I was collecting design references. We soon found that downloading the right image and keeping the button reliable across different sites required more work than the initial interaction suggested.

The Image-Saving Problem

I needed to save many design references from Instagram, Pinterest, and other sites. Each image required a right-click, “Save image as,” and a destination. Some sites offered only a low-resolution preview through that route.

That led me to an extension that would show a download button when the cursor moved over an image.

The First Version

The first design was straightforward: detect the image under the cursor, show a button beside it, and save the file on click.

I shared the idea with my friend Felix Falkenberg (@ffalkenberg). He works in ML and DevOps and is a digital nomad. We decided to build the extension together.

I had written a few Chrome extensions before, but they were short-lived tools for my own use and never reached the store. This time we intended to release something others could use, which meant accounting for different image structures and everyday interactions.

Detecting Hover

Hovering over an image on Instagram, a one-click download button appears in the bottom right corner

The finished extension displays a download button when the cursor moves over an image. In the first version, the button often flickered or disappeared as the cursor moved.

1
2
3
4
5
6
// First attempt: the naive approach
document.addEventListener('mouseover', function(e) {
if (e.target.tagName === 'IMG') {
showDownloadButton(e.target);
}
});

Testing revealed several problems:

  • The button flickered constantly
  • Performance problems made pages stutter
  • Some images were never detected
  • The button showed up in the wrong place

The first version did not account for the brief interval as the cursor moved from the image to the button. Adding a delay kept the button visible long enough to click.

Event Handling and Delay

After a few days of reading and testing, I learned why event delegation and debouncing matter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Optimized version
let hoverTimeout;
let currentImage = null;

document.addEventListener('mouseover', function(e) {
if (e.target.tagName === 'IMG' && e.target !== currentImage) {
clearTimeout(hoverTimeout);
hoverTimeout = setTimeout(() => {
showDownloadButton(e.target);
currentImage = e.target;
}, 200); // 200ms delay to stop the flicker
}
});

document.addEventListener('mouseout', function(e) {
if (e.target.tagName === 'IMG') {
clearTimeout(hoverTimeout);
setTimeout(() => {
hideDownloadButton();
}, 300); // give the user time to move onto the button
}
});

Finding the Original Image

Once the button appeared reliably, the next question was which image to download. Many sites show a thumbnail on the page, and downloading its src gives you only that thumbnail.

Image Sources on Google Images

Hovering over a Google Images search result, the ClickSave download button appears there too

On Google Images, the image element’s src often points to a low-resolution preview. Finding the original URL means checking other attributes and data structures on the page.

I spent a week testing its page structure. I ended up checking several places where the original URL might be stored:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Google Images high-res detection: the final version after endless trial and error
function getGoogleImagesHighRes(img) {
// Approach 1: check the various possible data attributes
const dataUrl = img.getAttribute('data-src') ||
img.getAttribute('data-original-src') ||
img.getAttribute('data-iurl');

// Approach 2: read the parent element's data-ri attribute (Google's metadata)
const parent = img.closest('[data-ri]');
if (parent) {
try {
const metadata = JSON.parse(parent.getAttribute('data-ri'));
// 'ou' is short for original URL
if (metadata.ou) return metadata.ou;
} catch (e) {
// JSON parse failed, fall through to the other approaches
}
}

// Approach 3: parse srcset for the highest resolution
if (img.srcset) {
const srcsetUrls = parseSrcset(img.srcset);
return srcsetUrls[srcsetUrls.length - 1].url;
}

// Approach 4: try to recover the original from the URL parameters
if (img.src.includes('googleusercontent.com')) {
return img.src.replace(/=s\d+/, ''); // strip the size constraint parameter
}

return img.src; // last resort fallback
}

Image Structures Across Sites

Then we found that every major site has its own logic for storing images:

  • Instagram: the high resolution image hides in data-* attributes, but the attribute names change
  • Twitter: you modify a URL parameter to get the large version (:large vs :small)
  • Pinterest: the original URL is hidden inside a complicated JSON structure
  • Facebook: image versions nested several layers deep, requiring a recursive search

Each site needed its own resolver:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class ImageResolver {
constructor() {
this.siteHandlers = {
'instagram.com': this.handleInstagram,
'twitter.com': this.handleTwitter,
'x.com': this.handleTwitter, // Twitter's domain after the rename
'images.google.com': this.handleGoogleImages,
'pinterest.com': this.handlePinterest,
'facebook.com': this.handleFacebook
};
}

async resolveHighResUrl(img) {
const hostname = window.location.hostname;
const handler = this.siteHandlers[hostname];

if (handler) {
try {
const result = await handler(img);
if (result && result !== img.src) return result;
} catch (error) {
console.warn(`Handler failed for ${hostname}:`, error);
}
}

// Generic fallback: try the common high-res patterns
return this.genericResolve(img);
}

handleTwitter(img) {
if (img.src.includes('pbs.twimg.com')) {
// swap :small or any other size for :large
return img.src.replace(/:(small|medium|thumb)/, ':large');
}
return img.src;
}
}

Designing the Download Button

With the technical problems solved, we started running into user experience problems we hadn’t anticipated.

Positioning a Draggable Button

At first we pinned the download button to the top right corner of the image, and problems showed up quickly:

  • On small images the button was overbearing
  • It sometimes covered something that mattered, a watermark or text
  • CSS from different sites interfered with how it rendered

We decided to make the button draggable, which brought a new technical problem: how do you keep the button inside the bounds of the image at all times?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Drag logic that keeps the button inside the image bounds
function constrainButtonPosition(button, image, newX, newY) {
const imgRect = image.getBoundingClientRect();
const btnRect = button.getBoundingClientRect();

// compute the valid drag range
const minX = 0;
const minY = 0;
const maxX = imgRect.width - btnRect.width;
const maxY = imgRect.height - btnRect.height;

// clamp to the bounds
const constrainedX = Math.max(minX, Math.min(maxX, newX));
const constrainedY = Math.max(minY, Math.min(maxY, newY));

return { x: constrainedX, y: constrainedY };
}

Filtering Decorative Images

During testing we hit something we hadn’t expected: a lot of sites are full of small decorative images, such as:

  • 1x1 pixel tracking images
  • repeating patterns used for background decoration
  • loading placeholders
  • CSS background images

A download button on those is useless and gets in the way.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Image filtering
function shouldShowDownloadButton(img) {
// drop images too small to be real content
if (img.width < 50 || img.height < 50) return false;

// drop the obvious tracking pixels
if (img.width === 1 && img.height === 1) return false;

// drop common placeholders and icons
const src = img.src.toLowerCase();
const suspiciousPatterns = [
'placeholder', 'loading', 'spinner', 'icon-',
'logo-small', 'avatar-default', '1x1', 'pixel'
];

if (suspiciousPatterns.some(pattern => src.includes(pattern))) {
return false;
}

// check whether it is a CSS background image
const computedStyle = window.getComputedStyle(img);
if (computedStyle.display === 'none' ||
computedStyle.visibility === 'hidden') {
return false;
}

// odd aspect ratios are usually dividers and other decoration
const aspectRatio = img.width / img.height;
if (aspectRatio > 20 || aspectRatio < 0.05) return false;

return true;
}

Button States and Visual Feedback

I added careful animation and state indicators:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
.download-button {
opacity: 0;
transform: scale(0.8);
transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
}

.download-button.show {
opacity: 1;
transform: scale(1);
}

.download-button:hover {
transform: scale(1.1);
box-shadow: 0 4px 12px rgba(0,0,0,0.3);
}

I wanted the button to be visible when needed and out of the way when the cursor moved off the image.

From Single to Batch Downloads

After friends tried the first version, someone asked if it could download every image on a page at once.

Felix and I started on batch downloads. We could not simply repeat the single-image flow dozens of times: we needed to limit concurrent requests and handle cases where some images failed.

Concurrency and Errors in Batch Downloads

ClickSave's side panel: every image on the page laid out in a grid, tick the ones you want and download them in one go

Batch downloading looks simple to implement and actually involves messy async work and error handling. We had to think about:

  • not firing too many download requests at once, since the browser will throttle you
  • handling the case where some downloads fail
  • giving the user progress feedback
  • avoiding duplicate downloads
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
class BatchDownloader {
async downloadAll(images) {
const results = [];
const concurrency = 3; // cap the concurrency

for (let i = 0; i < images.length; i += concurrency) {
const batch = images.slice(i, i + concurrency);
const promises = batch.map(img => this.downloadSingle(img));

try {
const batchResults = await Promise.allSettled(promises);
results.push(...batchResults);

// update progress
this.updateProgress(i + batch.length, images.length);

// keep the request rate down
await this.delay(500);
} catch (error) {
console.error('Batch download error:', error);
}
}

return results;
}
}

Code Structure and Refactoring

As features piled up the code got complicated and hard to maintain, so we refactored:

1
2
3
4
5
6
7
8
9
// Before: one giant file, 500+ lines
// After: a modular structure
const ClickSave = {
core: new CoreModule(),
ui: new UIModule(),
downloader: new DownloadModule(),
settings: new SettingsModule(),
analytics: new AnalyticsModule()
};

Supporting another site may require another handler. If all the logic stays in one file, each change requires tracing through the existing code again. After splitting the modules, adding a site mainly means implementing the relevant interface, with a clearer scope for maintenance.

Maintaining Support Across Sites

The main maintenance problem is that website structures change. Google Images may store the original URL in data attributes, Twitter uses URL parameters to distinguish sizes, and Pinterest may put image data in JSON. The extension needs a different way to identify each source. A site redesign can make a previously reliable download method stop working.

Working with Felix gave us different ways to check the design. Batch downloading is one example: too many simultaneous requests could trigger browser limits, so we decided on concurrency and failure handling before implementing the feature.

Next Steps

ClickSave has passed review and is available on the Chrome Web Store. Possible next steps include image upscaling and background removal, support for Firefox and Safari, and syncing settings across devices. Actual usage will help determine their priority.

From Practice Project to Store Release

Most extensions I built before this one stopped once the intended operation worked on my machine. Releasing ClickSave for others meant handling cases easy to miss in testing: tracking pixels, decorative images with unusual aspect ratios, changing data attributes, and the many ways someone might drag the button. Those details determine whether the extension remains reliable in regular use.


Project links: