# DownloadTrigger
Package: @mantine/core
Import: import { DownloadTrigger } from '@mantine/core';
Description: 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:

```tsx
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:

```tsx
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:

```tsx
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:

```tsx
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:

```tsx
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>
  );
}
```

## Server components

DownloadTrigger is not compatible with React Server Components as it uses useEffect and other client-side features. You can use it in client components only.


#### Props

**DownloadTrigger props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | (payload: DownloadTriggerPayload) => ReactNode | required | Children render function, provides an object with `download` handler and `loading` state |
| data | DownloadTriggerData | required | Content to download: a string, `Blob`, `File` or a function that returns/resolves to a `Blob` or string. The function is called when the download is triggered, which is useful for data that must be fetched or generated lazily. |
| fileName | string | - | Suggested name of the downloaded file, set as the `download` attribute of the underlying anchor. Defaults to `file.name` when `data` is (or resolves to) a `File` |
| mimeType | string | - | MIME type used to create a `Blob` when `data` is a string, for example, `'text/csv'` or `'application/json'` |
| onDownloadComplete | () => void | - | Called when the download is dispatched to the browser, not when the browser finishes saving the file |
| onError | (error: unknown) => void | - | Called when resolving `data` or dispatching the download fails. If not set, the error is rethrown |