Download buttons, a progress bar, and toasts for useDownload or useFetchDownload.

The download family renders one download hook. Download holds the hook, DownloadTrigger downloads one object, and DownloadProgress shows the bytes of a fetch download. One hook serves every trigger in the root, and each object key has its own state.

For a stored file with its download and delete actions, use ObjectCard.

Preview

One useFetchDownload hook for a list of files. While a file downloads, its button fills with the progress, and a click cancels it.

quarterly-report.pdf8.0 MB
brand-assets.zip24.0 MB
launch-video.mp416.0 MB

"use client";import { DownloadIcon } from "lucide-react";import { useFetchDownload } from "@dimah-s3/react";import {  Download,  DownloadToasts,  DownloadTrigger,  FileAttachment,} from "@dimah-s3/ui";const FILES = [  {    key: "uploads/3f1a/quarterly-report.pdf",    name: "quarterly-report.pdf",    type: "application/pdf",    size: 8 * 1024 * 1024,  },  {    key: "uploads/9b2e/brand-assets.zip",    name: "brand-assets.zip",    type: "application/zip",    size: 24 * 1024 * 1024,  },  {    key: "uploads/c47d/launch-video.mp4",    name: "launch-video.mp4",    type: "video/mp4",    size: 16 * 1024 * 1024,  },];export function DownloadDemo() {  // Fetches the bytes in the page, with progress and cancel.  const download = useFetchDownload({ route: "uploads" });  return (    <div className="mx-auto w-full max-w-md">      <Download download={download}>        <ul className="flex flex-col gap-2">          {FILES.map((file) => (            <li key={file.key}>              <FileAttachment                state="done"                fileName={file.name}                fileSize={file.size}                contentType={file.type}                actions={                  <DownloadTrigger                    objectKey={file.key}                    fileName={file.name}                    fileSize={file.size}                    variant="ghost"                    size="icon-xs"                    aria-label={`Download ${file.name}`}                    tooltip="Download"                  >                    <DownloadIcon />                  </DownloadTrigger>                }              />            </li>          ))}        </ul>      </Download>      <DownloadToasts download={download} />    </div>  );}

Install

Complete UI Setup first: the stylesheet and one <Toaster />. Then add this component:

import {
  Download,
  DownloadProgress,
  DownloadToasts,
  DownloadTrigger,
} from "@dimah-s3/ui";

Usage

"use client";

import { useDownload } from "@dimah-s3/react";
import { Download, DownloadToasts, DownloadTrigger } from "@dimah-s3/ui";

type Invoice = { key: string; name: string };

export function InvoiceList({ invoices }: { invoices: Invoice[] }) {
  const download = useDownload({ route: "invoices" });

  return (
    <>
      <Download download={download}>
        <ul>
          {invoices.map((invoice) => (
            <li key={invoice.key}>
              {invoice.name}
              <DownloadTrigger
                objectKey={invoice.key}
                fileName={invoice.name}
                size="sm"
              />
            </li>
          ))}
        </ul>
      </Download>
      <DownloadToasts download={download} />
    </>
  );
}

Download renders no element of its own. DownloadTrigger takes every Button prop, and children replace its icon and label.

Examples

Progress bar

DownloadProgress shows the bytes of a fetch download, next to the trigger that started it.

"use client";import { useFetchDownload } from "@dimah-s3/react";import {  Download,  DownloadProgress,  DownloadToasts,  DownloadTrigger,} from "@dimah-s3/ui";const REPORT = {  key: "uploads/5e8b/annual-report-2026.pdf",  name: "annual-report-2026.pdf",  size: 18 * 1024 * 1024,};export function DownloadProgressDemo() {  const download = useFetchDownload({ route: "uploads" });  return (    <div className="mx-auto flex w-full max-w-sm flex-col items-start gap-3">      <Download download={download}>        {/* While the file downloads, the button fills and turns into Cancel. */}        <DownloadTrigger          objectKey={REPORT.key}          fileName={REPORT.name}          fileSize={REPORT.size}        >          Download annual report        </DownloadTrigger>        <DownloadProgress objectKey={REPORT.key} />      </Download>      <DownloadToasts download={download} />    </div>  );}

Button styles

DownloadTrigger is a Button, so variant, size, and the other props are forwarded, and children replace the icon and label. An icon-only trigger needs an aria-label; while it cancels a fetch download, it shows only the cancel icon. These triggers use useDownload, which hands the file to the browser.

"use client";import { DownloadIcon, FileDownIcon } from "lucide-react";import { useDownload } from "@dimah-s3/react";import { Download, DownloadToasts, DownloadTrigger } from "@dimah-s3/ui";const KEY = "uploads/2c9a/price-list.pdf";export function DownloadVariantsDemo() {  // Signs a URL and hands it to the browser, which saves the file.  const download = useDownload({ route: "uploads" });  return (    <div className="flex flex-wrap items-center justify-center gap-2">      <Download download={download}>        <DownloadTrigger objectKey={KEY} fileName="price-list.pdf" />        <DownloadTrigger          objectKey={KEY}          fileName="price-list.pdf"          variant="default"        />        <DownloadTrigger          objectKey={KEY}          fileName="price-list.pdf"          variant="secondary"          size="sm"        >          <FileDownIcon data-icon="inline-start" />          Price list (PDF)        </DownloadTrigger>        <DownloadTrigger          objectKey={KEY}          fileName="price-list.pdf"          variant="link"        >          Download the price list        </DownloadTrigger>        <DownloadTrigger          objectKey={KEY}          fileName="price-list.pdf"          variant="ghost"          size="icon"          aria-label="Download price-list.pdf"          tooltip="Download"        >          <DownloadIcon />        </DownloadTrigger>      </Download>      <DownloadToasts download={download} />    </div>  );}

Navigate or fetch

The trigger follows the hook you pass to the root.

useDownload signs a URL and hands it to the browser, which saves the file. While the URL is signed, the trigger is disabled, stays focusable, and shows a spinner.
useFetchDownload fetches the bytes in the page. While the call runs, the trigger fills with the progress and a click cancels the download. Its label becomes "Cancel" and its accessible name Cancel download of {name}. The second click of a double-click does not cancel.

The trigger carries data-phase with the phase of the newest call for its key. See useDownload for both hooks.

Progress

DownloadProgress is a progress bar for the running fetch download of one key. It has role="progressbar", names the file, and reads the bytes received. It is indeterminate until the total size is known. Pass fileSize to the trigger to give the bar a total before the response does.

const download = useFetchDownload({ route: "exports" });

<Download download={download}>
  <DownloadTrigger objectKey={report.key} fileSize={report.size} />
  <DownloadProgress objectKey={report.key} />
</Download>;

It renders nothing with useDownload, which has no byte progress, and while no call for the key runs.

Toasts

Mount DownloadToasts once per hook, next to one <Toaster />.

useDownload: "Download started" once the browser has the URL.
useFetchDownload: a "Downloading" toast with the bytes and a Cancel action, then "Download complete".
Both: "Download failed" with the error, and "Download cancelled".

A second DownloadToasts for the same hook renders nothing and warns in development. Calls that settled before it mounted are not announced.

Props

import type {
  DownloadProps,
  DownloadTriggerProps,
  DownloadProgressProps,
  DownloadToastsProps,
} from "@dimah-s3/ui";

Download

Preview

Install

Usage

Examples

Progress bar

Button styles

Navigate or fetch

Progress

Toasts

Props

Download

DownloadTrigger

DownloadProgress

DownloadToasts

Frequently asked questions

On this page

Download

PreviewCopy Anchor Link

InstallCopy Anchor Link

UsageCopy Anchor Link

ExamplesCopy Anchor Link

Progress barCopy Anchor Link

Button stylesCopy Anchor Link

Navigate or fetchCopy Anchor Link

ProgressCopy Anchor Link

ToastsCopy Anchor Link

PropsCopy Anchor Link

DownloadCopy Anchor Link

DownloadTriggerCopy Anchor Link

DownloadProgressCopy Anchor Link

DownloadToastsCopy Anchor Link

Frequently asked questionsCopy Anchor Link

Can many rows share one hook?

How do I build my own trigger?

On this page

Preview

Install

Usage

Examples

Progress bar

Button styles

Navigate or fetch

Progress

Toasts

Props

Download

DownloadTrigger

DownloadProgress

DownloadToasts

Frequently asked questions