Skip prefetching anchors with the download attribute

sankalpsthakur · cursoragent · sankalpsthakur · commit ad007875fbe5 · 2026-07-22T14:32:45.000+05:30
Links marked for download often point at large binary payloads; excluding
them by default avoids wasted bandwidth while keeping ignores for custom cases.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/README.md b/README.md
@@ -409,6 +409,8 @@ quicklink.listen({
 
 ### Custom Ignore Patterns
 
+By default, quicklink skips anchors that have a [`download`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download) attribute, since those often point at large binary payloads.
+
 These filters run _after_ the `origins` matching has run. Ignores can be useful for avoiding large file downloads or for responding to DOM attributes dynamically.
 
 ```js
diff --git a/src/chunks.mjs b/src/chunks.mjs
@@ -106,8 +106,9 @@ export function listen(options = {}) {
   });
 
   timeoutFn(() => {
-    // Find all links & Connect them to IO if allowed
-    const links = (options.el || document).querySelectorAll('a[href]');
+    // Find all links & Connect them to IO if allowed.
+    // Skip anchors with the `download` attribute (large payloads).
+    const links = (options.el || document).querySelectorAll('a[href]:not([download])');
     for (const link of links) {
       // If the anchor matches a permitted origin
       // ~> A `[]` or `true` means everything is allowed
diff --git a/src/index.mjs b/src/index.mjs
@@ -206,11 +206,15 @@ export function listen(options = {}) {
   });
 
   timeoutFn(() => {
-    // Find all links & Connect them to IO if allowed
+    // Find all links & Connect them to IO if allowed.
+    // Skip anchors with the `download` attribute — those often point at large
+    // binary payloads that are wasteful to prefetch.
     const isAnchorElement = options.el && options.el.length > 0 && options.el[0].nodeName === 'A';
-    const elementsToListen = isAnchorElement ? options.el : (options.el || document).querySelectorAll('a');
+    const elementsToListen = isAnchorElement ? options.el : (options.el || document).querySelectorAll('a:not([download])');
 
     for (const link of elementsToListen) {
+      // NodeList of anchors may still include download links
+      if (link.hasAttribute('download')) continue;
       // If the anchor matches a permitted origin
       // ~> A `[]` or `true` means everything is allowed
       if (!allowed.length || allowed.includes(link.hostname)) {
diff --git a/test/fixtures/test-ignore-download.html b/test/fixtures/test-ignore-download.html
@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>Prefetch: Ignore download attribute</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="main.css">
+</head>
+
+<body>
+  <a href="1.html">Link 1</a>
+  <a href="2.html" download>Download Link 2</a>
+  <a href="3.html" download="report.pdf">Download Link 3</a>
+  <a href="4.html" style="position:absolute;margin-top:900px;">Link 4</a>
+  <script src="../../dist/quicklink.umd.js"></script>
+  <script>
+    quicklink.listen();
+  </script>
+</body>
+
+</html>
diff --git a/test/quicklink.spec.js b/test/quicklink.spec.js
@@ -207,6 +207,24 @@ mainSuite('should only prefetch links after ignore patterns allowed it', async c
   assert.not.ok(responseURLs.includes('https://github.githubassets.com/images/spinners/octocat-spinner-32.gif'));
 });
 
+mainSuite('should not prefetch links with the download attribute', async context => {
+  const responseURLs = [];
+  context.page.on('response', resp => {
+    responseURLs.push(resp.url());
+  });
+  await context.page.goto(`${server}/test-ignore-download.html`);
+  await sleep();
+  assert.instance(responseURLs, Array);
+
+  assert.ok(responseURLs.includes(`${server}/1.html`));
+  // boolean download attribute
+  assert.not.ok(responseURLs.includes(`${server}/2.html`));
+  // download="filename" attribute
+  assert.not.ok(responseURLs.includes(`${server}/3.html`));
+  // out of viewport
+  assert.not.ok(responseURLs.includes(`${server}/4.html`));
+});
+
 mainSuite('should only prefetch links after ignore patterns allowed it (multiple)', async context => {
   const responseURLs = [];
   context.page.on('response', resp => {
