# File export

> File export helpers for React apps: download blobs, text and JSON, turn a canvas or an SVG into a PNG, copy images and name files cleanly.

- Type: React helper (Hooks & Utilities)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add file-export`
- Docs: https://wingo-ui.com/components/file-export

## Interaction

The card is an SVG. Download SVG saves it as it is, Download PNG rasterizes it at the playground scale (with the background color when one is set), Copy PNG puts the image on the clipboard (paste it into a chat or a doc), and Download JSON saves the card's data. Every file is named from the title plus the local date and time, and the readout shows the last name and size.

## Installation

```bash
npx wingo-ui@latest add file-export
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/file-export` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `lib/file-export.ts`

## Usage

```tsx
import { svgToImageBlob, downloadBlob, timestampedFileName } from "@/lib/file-export"

export function DownloadQr({ svg }: { svg: SVGSVGElement | null }) {
  return (
    <button
      type="button"
      onClick={async () => {
        if (!svg) return
        const png = await svgToImageBlob(svg, { scale: 4, background: "#ffffff" })
        downloadBlob(png, timestampedFileName("invoice-qr-code", "png"))
      }}
    >
      Download PNG
    </button>
  )
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scale?` | `number` | `2` | svgToImageBlob(svg, { scale }): device pixels per CSS pixel of the PNG. 2 keeps exports sharp on retina screens and in print. |
| `background?` | `string` | `""` | svgToImageBlob(svg, { background }): a fill behind the image; empty keeps the PNG transparent. |
| `fileName?` | `string` | `"Certificate Emma Carter"` | The base passed to timestampedFileName(base, extension): diacritics and unsafe characters are removed, the local date and time are appended. |
| `downloadBlob?` | `(blob: Blob, filename: string) => void` |  | The main helper: saves a Blob under a file name through a temporary object URL, released right after. Browser only; call it from an event handler, never during render. |

## Parts

### downloadUrl (function)

Saves a URL (same origin, or a data: or blob: URL) under a file name through a temporary link. Browser only, for event handlers.

### downloadText (function)

Saves text such as a log, a diff or a CSV under a file name. Options: type (default text/plain) and bom, which prefixes a UTF-8 BOM so Excel on Windows reads accented letters.

### downloadJson (function)

Saves any value as pretty-printed JSON (2 spaces by default) under a file name.

### canvasToBlob (function)

canvas.toBlob as a promise for PNG, JPEG or WebP. Rejects when a cross-origin image has tainted the canvas.

### serializeSvg (function)

Standalone SVG text from an element or a string, with the namespaces and XML header added so the file opens in any viewer.

### svgToBlob (function)

The same standalone SVG as an image/svg+xml Blob, ready for downloadBlob.

### svgToImageBlob (function)

Draws an SVG into a canvas and returns a PNG, JPEG or WebP Blob: QR codes, signatures, charts. Options: width, height, scale (default 2), background, type, quality. The size defaults to the SVG's own width, height or viewBox.

### loadImage (function)

An image ready for drawImage from a URL, a data URL or a File or Blob; an object URL is released once the image decodes. Croppers and avatar uploads use it.

### blobToDataUrl (function)

A data: URL from a Blob, for previews and small uploads.

### canCopyImages (function)

Whether this browser can put an image on the clipboard (ClipboardItem and clipboard.write exist). Check it in an effect or a handler and hide the Copy button when it is false.

### copyImageToClipboard (function)

Puts a PNG on the clipboard. Pass the promise itself from the click handler, not an awaited blob: Safari only allows the write when the clipboard item is created inside the gesture. Resolves false when unsupported or denied.

### shareFile (function)

Opens the phone's share sheet with a file, title and text. Resolves false where files cannot be shared, so the caller can download instead.

### sanitizeFileName (function)

Strips what file systems refuse and keeps names readable: "Invoice #12/2026" becomes "Invoice-12-2026", "Café menu" becomes "Cafe-menu". Falls back to "file" when nothing is left.

### timestampedFileName (function)

A clean base name plus the local date and time, so repeated exports never collide: ("Signature", "png") gives "Signature-2026-09-24-1640.png".

### ImageType (type)

"image/png" | "image/jpeg" | "image/webp", the raster formats the helpers produce.

### RasterizeOptions (type)

svgToImageBlob's options: width, height, scale, background, type, quality.

## Examples

- **Clean file names**: sanitizeFileName strips what file systems refuse; the timestamp keeps exports from colliding.
- **Export a report**: downloadText with a BOM for Excel, and downloadJson for the same rows.
- **Copy a chart**: copyImageToClipboard with the rasterize promise passed straight from the click.

## See also

- [useClipboard](https://wingo-ui.com/components/use-clipboard) ([Markdown](https://wingo-ui.com/components/use-clipboard.md))
- [File types](https://wingo-ui.com/components/file-types) ([Markdown](https://wingo-ui.com/components/file-types.md))
- [Spreadsheet](https://wingo-ui.com/components/spreadsheet) ([Markdown](https://wingo-ui.com/components/spreadsheet.md))

---

Canonical: https://wingo-ui.com/components/file-export
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt