DownloadTrigger

Trigger a client-side file download

Usage

DownloadTrigger downloads generated content (CSV, JSON, images) as a file without a server request. It does not render any element, its children is a function that receives:

  • download – function that starts the download
  • loading – true while an async data function is resolving

data can be a string, a Blob or a File. Set mimeType prop when data is a string:

import { Button, DownloadTrigger } from '@mantine/core';

const csv = `name,role
Alice,Engineer
Bob,Designer`;

function Demo() {
  return (
    <DownloadTrigger data={csv} fileName="report.csv" mimeType="text/csv">
      {({ download }) => <Button onClick={download}>Export CSV</Button>}
    </DownloadTrigger>
  );
}

Async data

data can be a function that returns the content or a promise that resolves with it. While it is resolving, loading is true and repeated download calls are ignored:

import { Button, DownloadTrigger } from '@mantine/core';

async function generateReport(): Promise<string> {
  await new Promise((resolve) => {
    setTimeout(resolve, 1500);
  });
  return JSON.stringify({ value: 42, items: [1, 2, 3] }, null, 2);
}

function Demo() {
  return (
    <DownloadTrigger data={generateReport} fileName="report.json" mimeType="application/json">
      {({ download, loading }) => (
        <Button onClick={download} loading={loading}>
          Generate & download
        </Button>
      )}
    </DownloadTrigger>
  );
}

Error handling

If resolving data or the download fails, the error is passed to onError. Without onError, the error is rethrown:

import { useState } from 'react';
import { Button, DownloadTrigger, Stack, Text } from '@mantine/core';

async function generateReport(): Promise<string> {
  await new Promise((resolve) => {
    setTimeout(resolve, 1000);
  });
  throw new Error('Server is not available');
}

function Demo() {
  const [error, setError] = useState<string | null>(null);

  return (
    <Stack align="center">
      <DownloadTrigger
        data={generateReport}
        fileName="report.json"
        onError={(err) => setError(err instanceof Error ? err.message : 'Download failed')}
        onDownloadComplete={() => setError(null)}
      >
        {({ download, loading }) => (
          <Button color="red" onClick={download} loading={loading}>
            Download (will fail)
          </Button>
        )}
      </DownloadTrigger>

      {error && (
        <Text c="red" size="sm">
          {error}
        </Text>
      )}
    </Stack>
  );
}

Custom trigger

Children can return any element: a button, an action icon, a menu item or your own component. Call download from its onClick handler:

import { DownloadIcon } from '@phosphor-icons/react';
import { ActionIcon, DownloadTrigger } from '@mantine/core';

const csv = `name,role
Alice,Engineer
Bob,Designer`;

function Demo() {
  return (
    <DownloadTrigger data={csv} fileName="report.csv" mimeType="text/csv">
      {({ download }) => (
        <ActionIcon variant="light" size="lg" aria-label="Download CSV" onClick={download}>
          <DownloadIcon size={20} />
        </ActionIcon>
      )}
    </DownloadTrigger>
  );
}

Accessibility

When the trigger is icon-only, set aria-label to describe the action:

import { ActionIcon, DownloadTrigger } from '@mantine/core';

function Demo() {
  return (
    <DownloadTrigger data="data" fileName="file.txt">
      {({ download }) => (
        <ActionIcon aria-label="Download file" onClick={download}>
          ⬇
        </ActionIcon>
      )}
    </DownloadTrigger>
  );
}

Incompatible with server components

DownloadTrigger is not compatible with React server components because it requires using function as children. To use DownloadTrigger, add "use client;" at the top of the file.