Download Helper

Save a Blob

DownloadHelper.save() starts a browser download for a Blob. Set the Blob’s MIME type when you create it; the helper does not infer one from the file name.

import { DownloadHelper } from '@oardi/ts-utils';

const content = new Blob(['Hello world'], {
	type: 'text/plain;charset=utf-8',
});

DownloadHelper.save(content, 'hello.txt');

The file name is optional. When it is missing or empty, the helper uses the name of a File input or falls back to download for a plain Blob.

Call save() directly from a user interaction, such as a button click, to avoid browser download restrictions.

Download fallback

The helper uses a temporary download link with the requested or fallback file name. The link also targets a new tab so browsers that ignore the download attribute, including some iOS/WebKit versions and file types, can display the Blob for manual saving instead of replacing the current page.

This behavior is best effort. Browser settings can affect the result, and the requested file name is not guaranteed when a Blob is opened in a tab.

Add a UTF-8 byte order mark

Set autoBom to add a UTF-8 byte order mark (BOM) to compatible text or XML blobs. The Blob type must explicitly use charset=utf-8; other Blob types remain unchanged.

const report = new Blob(['id,name\n1,Ada'], {
	type: 'text/csv;charset=utf-8',
});

DownloadHelper.save(report, 'report.csv', {
	autoBom: true,
});

The helper supports UTF-8 MIME types matching text/*, application/xml, or */*+xml.

Browser requirements

DownloadHelper requires window, document, and the object URL APIs. Calling save() during server-side rendering throws an error. The temporary download element and object URL are cleaned up automatically.