# @capgo/capacitor-downloader Download large files in the background or foreground from your Capacitor app, with pause, resume and progress events. Downloads keep going when users leave the screen. Capgo - Build Capacitor apps with AI, ship updates instantly

Capgo: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.

➡️ Get started for free

14-day unlimited free trial. No credit card required

> 🤖 **Building with an AI coding agent?** Install [Capgo skills](https://capgo.app/skills/?ref=plugin_downloader) so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use `@capgo/capacitor-downloader` in your Capacitor app: `npx skills add Cap-go/capgo-skills`. Then ask your agent: *"Add @capgo/capacitor-downloader to my Capacitor app and wire it up."* [Agent setup guides](https://capgo.app/agents/?ref=plugin_downloader) · [Hosted MCP](https://capgo.app/docs/ai/mcp/?ref=plugin_downloader)

@capgo/capacitor-downloader for Capacitor apps

## Key features - **Downloads**: `download()` starts a task with optional HTTP headers and a `wifi-only` or cellular network rule. - **Control**: `pause()`, `resume()` and `stop()` for each download ID. - **Progress events**: `downloadProgress`, `downloadCompleted` and `downloadFailed` listeners. - **Status and files**: `checkStatus()` for a task and `getFileInfo()` for a downloaded file. - **Platforms**: iOS and Android. iOS uses a background `URLSession`, Android uses `DownloadManager`. Not available on web. ## 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/ ## Compatibility | Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.\*.\* | v8.\*.\* | ✅ | | v7.\*.\* | v7.\*.\* | On demand | | v6.\*.\* | v6.\*.\* | ❌ | | v5.\*.\* | v5.\*.\* | ❌ | > **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained. ## Install You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command: ```bash npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins ``` Then use the following prompt: ```text Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-downloader` plugin in my project. ``` If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below: ```bash npm install @capgo/capacitor-downloader npx cap sync ``` ## API * [`download(...)`](#download) * [`pause(...)`](#pause) * [`resume(...)`](#resume) * [`stop(...)`](#stop) * [`checkStatus(...)`](#checkstatus) * [`getFileInfo(...)`](#getfileinfo) * [`addListener('downloadProgress', ...)`](#addlistenerdownloadprogress-) * [`addListener('downloadCompleted', ...)`](#addlistenerdownloadcompleted-) * [`addListener('downloadFailed', ...)`](#addlistenerdownloadfailed-) * [`removeAllListeners()`](#removealllisteners) * [`getPluginVersion()`](#getpluginversion) * [Interfaces](#interfaces) Capacitor plugin for downloading files with background support. Provides resumable downloads with progress tracking. ### download(...) ```typescript download(options: DownloadOptions) => Promise ``` Start a new download task. | Param | Type | Description | | ------------- | ----------------------------------------------------------- | ------------------------ | | **`options`** | DownloadOptions | - Download configuration | **Returns:** Promise<DownloadTask> -------------------- ### pause(...) ```typescript pause(options: { id: string; }) => Promise ``` Pause an active download. Download can be resumed later from the same position. | Param | Type | Description | | ------------- | ---------------------------- | ----------------------------------------- | | **`options`** | { id: string; } | - Options containing the download task ID | -------------------- ### resume(...) ```typescript resume(options: { id: string; }) => Promise ``` Resume a paused download. Continues from where it was paused. | Param | Type | Description | | ------------- | ---------------------------- | ----------------------------------------- | | **`options`** | { id: string; } | - Options containing the download task ID | -------------------- ### stop(...) ```typescript stop(options: { id: string; }) => Promise ``` Stop and cancel a download permanently. Downloaded data will be deleted. | Param | Type | Description | | ------------- | ---------------------------- | ----------------------------------------- | | **`options`** | { id: string; } | - Options containing the download task ID | -------------------- ### checkStatus(...) ```typescript checkStatus(options: { id: string; }) => Promise ``` Check the current status of a download. | Param | Type | Description | | ------------- | ---------------------------- | ----------------------------------------- | | **`options`** | { id: string; } | - Options containing the download task ID | **Returns:** Promise<DownloadTask> -------------------- ### getFileInfo(...) ```typescript getFileInfo(options: { path: string; }) => Promise<{ size: number; type: string; }> ``` Get information about a downloaded file. | Param | Type | Description | | ------------- | ------------------------------ | ---------------------------------- | | **`options`** | { path: string; } | - Options containing the file path | **Returns:** Promise<{ size: number; type: string; }> -------------------- ### addListener('downloadProgress', ...) ```typescript addListener(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; bytesWritten?: number | undefined; bytesTotal?: number | undefined; }) => void) => Promise ``` Listen for download progress updates. Fired periodically as download progresses. | Param | Type | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | **`eventName`** | 'downloadProgress' | - Must be 'downloadProgress' | | **`listenerFunc`** | (progress: { id: string; progress: number; bytesWritten?: number; bytesTotal?: number; }) => void | - Callback receiving progress updates | **Returns:** Promise<PluginListenerHandle> -------------------- ### addListener('downloadCompleted', ...) ```typescript addListener(eventName: 'downloadCompleted', listenerFunc: (result: { id: string; }) => void) => Promise ``` 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', ...) ```typescript addListener(eventName: 'downloadFailed', listenerFunc: (error: { id: string; error: string; }) => void) => Promise ``` 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() ```typescript removeAllListeners() => Promise ``` Remove all event listeners. Cleanup method to prevent memory leaks. -------------------- ### getPluginVersion() ```typescript 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 | Since | | ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **`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 | | | **`notification`** | 'completed' \| 'progress' \| 'hidden' | Android DownloadManager notification visibility. - `'completed'` (default): show while downloading and keep the notification after completion. - `'progress'`: show while downloading, remove the notification when finished. - `'hidden'`: no system notification; use plugin progress events instead. Ignored on iOS and Web. | 8.2.0 | #### PluginListenerHandle | Prop | Type | | ------------ | ----------------------------------------- | | **`remove`** | () => Promise<void> | ### Credit This plugin was inspired from: https://github.com/kesha-antonov/react-native-background-downloader