My Journey to Implement a Button to Download a File

Welcome

We have recently released a feature allowing users to download the summary of their load tests as a CSV file. My mission was pretty straightforward: display a simple button, labeled “Download CSV”, that would trigger the download of the file when the user clicks on it.

export interface DownloadableResponse {
  blob: Blob;
  filename: string;
}

Our client layer is responsible for building this object from the server response when we request the CSV data for a simulation.

This is our blobMapper. The code responsible for mapping Axios responses with blob into our DownloadableResponse.

export const blobMapper = (response: AxiosResponse<BlobPart>): DownloadableResponse => ({
  blob: new Blob([response.data]),
  filename: getFilenameFromHeaders(response.headers)
});

The getFilenameFromHeaders is a custom method that extracts the filename from the “content-disposition” header. If you’re interested in it, be my guest:

const CONTENT_DISPOSITION_HEADER = "content-disposition";

export const getFilenameFromHeaders = (headers: RawAxiosResponseHeaders | AxiosResponseHeaders): string => {
  const headerLine = headers[CONTENT_DISPOSITION_HEADER];
  if (!headerLine) {
    throw new Error(`could not find '${CONTENT_DISPOSITION_HEADER}' header`);
  }

  try {
    return headerLine.split("filename=")[1].replace(/"/g, "");
  } catch {
    throw new Error(`could not parse '${CONTENT_DISPOSITION_HEADER}' header`);
  }
};

From there, we can start building the hook:

interface FileDownload {
  download: () => void;
}

export const useDownloadFile = (request: () => Promise<DownloadableResponse>): FileDownload => {
[...]
}

The hook accepts only one argument, a request builder. Then it returns an object that provides a download callback.

Creating the anchor

The first thing the hook needs to do is instantiate an anchor element in the DOM, and remove it from the DOM when the component using it is unmounted.

const anchorRef = useRef<HTMLAnchorElement | null>(null);

useEffect(() => {
    const anchor = document.createElement("a");
    anchor.style.display = "none";
    anchorRef.current = anchor;
    document.body.appendChild(anchor);

    return () => {
      document.body.removeChild(anchor);
    };
  }, []);

As you can see:

• We keep a reference to the anchor (anchorRef) as we need to set its URL and virtually click on it later.
• We set its CSS display property to “none” as we do not want it to appear anywhere.
• We provide an empty array of dependencies to useEffect, as we want this code to be run only on the mounting and unmounting of the component. Be careful! Providing no array at all would be a mistake, as the code would be run at every render!

Building the download callback

The download callback is pretty straightforward too:

const download = useCallback(() => {
  request()
    .then(({ blob, filename }) => {
      const url = URL.createObjectURL(blob);
      if (anchorRef.current) {
        anchorRef.current.href = url;
        anchorRef.current.download = filename;
        anchorRef.current.click();
      }
    })
    .catch(() => {
// Handle error here
    });
}, [request]);

• We execute the request, and we get the blob’s URL by calling URL.createObjectURL from the browser API.
• We bind the anchor to that URL.
• We set the download filename property.
• And we click on it!

Deleting the blob

At this point, our hook is functional. But we still need to address one last thing: we want the blob to be deleted from the browser memory when we unmount the component.

Why not remove it as soon as the download finishes, you may ask? That would be better, indeed, but no browser API provides such a callback. So, unmounting it is!

To do that, we need to invoke URL.revokeObjectURL with the blob’s URL. So, we need to keep track of it using a local state.

const [url, setUrl] = useState("");

const download = useCallback(() => {
  request()
    .then(({ blob, filename }) => {
      const url = URL.createObjectURL(blob);
      setUrl(url); // Keeping the URL in a local state

      if (anchorRef.current) {
        anchorRef.current.href = url;
        anchorRef.current.download = filename;
        anchorRef.current.click();
      }
    })
    .catch(() => {
// Handle error here
    });
}, [request]);

Then, another useEffect handles the blob revocation.

useEffect(() => {
    const toRevoke = url;
    return () => {
      if (toRevoke) {
        URL.revokeObjectURL(toRevoke);
      }
    };
  }, [url]);

Please note that URL.revokeObjectURL does not ensure that the blob is released from memory, as browsers may handle the memory themselves (to prevent download fails if an object is revoked too early, for instance). From my tests, the blob revocation worked great on Chromium-based browsers, but not with Firefox.

Wrapping it up and testing!

At this point, our custom hook looks like this:

interface FileDownload {
  download: () => void;
}

export const useDownloadFile = (request: () => Promise<DownloadableResponse>): FileDownload => {
const anchorRef = useRef<HTMLAnchorElement | null>(null);
const [url, setUrl] = useState("");

useEffect(() => {
    const anchor = document.createElement("a");
    anchor.style.display = "none";
    anchorRef.current = anchor;
    document.body.appendChild(anchor);

    return () => {
      document.body.removeChild(anchor);
    };
  }, []);

useEffect(() => {
    const toRevoke = url;
    return () => {
      if (toRevoke) {
        URL.revokeObjectURL(toRevoke);
      }
    };
  }, [url]);

const download = useCallback(() => {
  request()
    .then(({ blob, filename }) => {
      const url = URL.createObjectURL(blob);
setUrl(url);
      if (anchorRef.current) {
        anchorRef.current.href = url;
        anchorRef.current.download = filename;
        anchorRef.current.click();
      }
    })
    .catch(() => {
// Handle error here
    });
}, [request]);

return { download };
}

Using the hook is very simple.

const ExportCsvButton = (): ReactElement => {
  const { download } = useDownloadFile(/* our Axios request builder */);

  return (
    <Button
      icon="download"
      label="Download CSV"
      variant="info"
      onClick={download}
    />
  );
};

And it works like a charm!

Going further

Adding a status

Our hook works great, and we can still go a little further. As it stands, if the user clicks the button multiple times in quick succession, the download will be initiated multiple times. Again, we are not able to determine whether the download is completed or not, but we could at least wait for the server response before allowing clicking again, right?

Plus, we have already developed a custom button component that accepts an isLoading boolean prop and changes the button’s icon to a loader when it’s truthy. It would be great if the hook provided a status property along with the callback, indicating whether the download is ready or if the user has already clicked the button, for example.

So let’s do this!

In the FileDownload object returned by the hook, we add a status property.

type DownloadStatus = "initializing" | "ready" | "pending";

interface FileDownload {
  download: () => void;
  status: DownloadStatus;
}

Let’s also add a local state, set to initializing by default to keep track of the status.

const [status, setStatus] =
useState<DownloadStatus>("initializing");

When the anchor is created in the first effect, we can set the status to ready.

useEffect(() => {
    const anchor = document.createElement("a");
    anchor.style.display = "none";
    anchorRef.current = anchor;
    document.body.appendChild(anchor);

    setStatus("ready"); // <-- here!

    return () => {
      document.body.removeChild(anchor);
    };
  }, []);

As soon as the user clicks the button (i.e., invokes the download callback), we can set the status to pending. When the request is done, whether it succeeded or failed, we set the status back to ready, using the finally callback from the Promises API.

const download = useCallback(() => {
  setStatus("pending"); // <-- the user has clicked, status is "pending"
  request()
    .then(({ blob, filename }) => {
      const url = URL.createObjectURL(blob);
      if (anchorRef.current) {
        anchorRef.current.href = url;
        anchorRef.current.download = filename;
        anchorRef.current.click();
      }
    })
    .catch(() => {
      // Handle error here
    })
    .finally(() => {
        setStatus("ready");  // <-- back to "ready"
    });
}, [request]);

Finally, let’s return the status along with the download callback, and bind it to our custom LoadingButton.

const ExportCsvButton = (): ReactElement => {
  const { download, status } = useDownloadFile(/* our Axios request builder */);

  return (
    <LoadingButton
      icon="download"
      label="Download CSV"
      variant="info"
      disabled={status !== "ready"}
      isLoading={status === "pending"}
      onClick={download}
    />
  );
};

Good! Now, the button is disabled until the download is ready. Besides, while the server responds, the button is disabled and its icon is replaced by a loader! How cool is that?

Typing our blob

Blobs are cool. But you know what’s even cooler? Typed blobs.

The browser API allows us to indicate our blob type when creating them.

Remember our blobMapper from earlier? Let’s tweak it a little more.

export const blobMapper = (response: AxiosResponse<BlobPart>): 
DownloadableResponse => ({
  blob: new Blob([response.data], { type:
 response.headers["content-type"] ?? "application/octet-stream"
 }),
  filename: getFilenameFromHeaders(response.headers)
});

We take advantage of the content-type header to type our blob accordingly. If the header is not present, we at least fall back to octet-stream.

And just like that, we avoid having an “unknown type” blob. 🙂

Promises ≠ Observables

Another pitfall I’ve fallen into is that as a former Angular developer, I have worked way more with Observables than Promises. As a result, I didn’t wrap my request in a builder at first, thinking that it would be triggered when the user clicked on the button (as Observables are not triggered until something really subscribes to it).

It looked like this. Please do not reproduce!

/* WRONG ! The response promise was not wrapped in a builder */
export const useDownloadFile = (response: Promise<DownloadableResponse>): FileDownload => {
[...]
const download = useCallback(() => {
    response
      .then(({ blob, filename }) => [...]
}

See? The problem here is that as soon as the component is mounted, the response would require to build the download callback! Consequently, the request to the server is made even if the user hasn’t clicked the button yet. I’m making a data request unnecessarily, without any guarantee of its usefulness.

Wrapping your response into a builder prevents this, as the builder will only be called when the callback is!

/* RIGHT ! The response promise is wrapped in a builder */
export const useDownloadFile = (request: () => Promise<DownloadableResponse>): FileDownload => {
[...]
const download = useCallback(() => {
    request()
      .then(({ blob, filename }) => [...]
}

Final thoughts and takeaways

Even if it’s not perfect, the hook works great.

Still, there’s some direct DOM manipulation with appendChild, removeChild, and element.click(), but we managed to integrate the hacky way of triggering a download via XHR request into the React lifecycle. Plus, the hack is contained inside a single hook, so if we ever find a better way to do this in the future, we only have a single file to edit.

As you can see, something as simple as implementing a button to download a file can imply lots of hidden pitfalls. Let’s sum them up!

• XHR requests can’t trigger download prompts. Different APIs, different responsibilities.
• If you are left with a hacky way of doing something, you should still try to make it as clean and contained as possible.
• You should stick with your framework/library lifecycle.
• Type your blobs! And clean them when they aren’t needed anymore.
• Make sure your requests are effectively executed when you need the result, not necessarily when your component is mounted. 😊

I hope you enjoyed reading this as much as I enjoyed writing it. Until then, happy testing everyone!

Related resources

You might also be interested in…