@capgo/capacitor-downloader

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

Download file in background or foreground

Why Capacitor Downloader?

A reliable native file downloader built for Capacitor apps that continues downloads even when your app is backgrounded or closed:

• Background downloads - Downloads continue even when app is minimized, backgrounded, or closed (main advantage)
• Progress tracking - Real-time progress updates during downloads
• Network control - Choose between WiFi-only or cellular network downloads
• Custom headers - Add authentication tokens and custom HTTP headers
• Resumable downloads - Pause and resume downloads (platform dependent)
• Event listeners - Monitor download progress, completion, and failures
• Large file support - Handle multi-gigabyte files without memory issues
• Free and open source - No paid services required

Perfect for downloading large media files, offline content, app updates, and any scenario where downloads need to survive app lifecycle events.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/downloader/

Install

npm install @capgo/capacitor-downloader
npx cap sync

API

• download(...)
• pause(...)
• resume(...)
• stop(...)
• checkStatus(...)
• getFileInfo(...)
• addListener('downloadProgress', ...)
• addListener('downloadCompleted', ...)
• addListener('downloadFailed', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces

Capacitor plugin for downloading files with background support. Provides resumable downloads with progress tracking.

download(...)

download(options: DownloadOptions) => Promise<DownloadTask>

Start a new download task.

Param	Type	Description
options	DownloadOptions	- Download configuration

Returns: Promise<DownloadTask>

---

pause(...)

pause(id: string) => Promise<void>

Pause an active download. Download can be resumed later from the same position.

Param	Type	Description
id	string	- ID of the download task to pause

---

resume(...)

resume(id: string) => Promise<void>

Resume a paused download. Continues from where it was paused.

Param	Type	Description
id	string	- ID of the download task to resume

---

stop(...)

stop(id: string) => Promise<void>

Stop and cancel a download permanently. Downloaded data will be deleted.

Param	Type	Description
id	string	- ID of the download task to stop

---

checkStatus(...)

checkStatus(id: string) => Promise<DownloadTask>

Check the current status of a download.

Param	Type	Description
id	string	- ID of the download task to check

Returns: Promise<DownloadTask>

---

getFileInfo(...)

getFileInfo(path: string) => Promise<{ size: number; type: string; }>

Get information about a downloaded file.

Param	Type	Description
path	string	- Local file path to inspect

Returns: Promise<{ size: number; type: string; }>

---

addListener('downloadProgress', ...)

addListener(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; }) => void) => Promise<PluginListenerHandle>

Listen for download progress updates. Fired periodically as download progresses.

Param	Type	Description
eventName	'downloadProgress'	- Must be 'downloadProgress'
listenerFunc	(progress: { id: string; progress: number; }) => void	- Callback receiving progress updates

Returns: Promise<PluginListenerHandle>

---

addListener('downloadCompleted', ...)

addListener(eventName: 'downloadCompleted', listenerFunc: (result: { id: string; }) => void) => Promise<PluginListenerHandle>

Listen for download completion. Fired when a download finishes successfully.

Param	Type	Description
eventName	'downloadCompleted'	- Must be 'downloadCompleted'
listenerFunc	(result: { id: string; }) => void	- Callback receiving completion notification

Returns: Promise<PluginListenerHandle>

---

addListener('downloadFailed', ...)

addListener(eventName: 'downloadFailed', listenerFunc: (error: { id: string; error: string; }) => void) => Promise<PluginListenerHandle>

Listen for download failures. Fired when a download encounters an error.

Param	Type	Description
eventName	'downloadFailed'	- Must be 'downloadFailed'
listenerFunc	(error: { id: string; error: string; }) => void	- Callback receiving error information

Returns: Promise<PluginListenerHandle>

---

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all event listeners. Cleanup method to prevent memory leaks.

---

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the plugin version number.

Returns: Promise<{ version: string; }>

---

Interfaces

DownloadTask

Represents the current state and progress of a download task.

Prop	Type	Description
id	string	Unique identifier for the download task
progress	number	Download progress from 0 to 100
state	'PENDING' | 'RUNNING' | 'PAUSED' | 'DONE' | 'ERROR'	Current state of the download

DownloadOptions

Configuration options for starting a download.

Prop	Type	Description
id	string	Unique identifier for this download task
url	string	URL of the file to download
destination	string	Local file path where the download will be saved
headers	{ [key: string]: string; }	Optional HTTP headers to include in the request
network	'cellular' | 'wifi-only'	Network type requirement for download
priority	'high' | 'normal' | 'low'	Download priority level

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

Credit

This plugin was inspired from: https://github.com/kesha-antonov/react-native-background-downloader