@capgo/capacitor-file-sharer

Share files through the native share sheet from your Capacitor app, or save them to the device on Android. On web, the same calls download the file.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-file-sharer in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-file-sharer to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Share: share() opens the native share sheet on iOS and Android.
• Save: on Android, save() stores the file with MediaStore where supported and a legacy path on older versions. On iOS it opens the share sheet so the user picks the destination.
• Flexible input: pass base64 data or a local file.
• Web fallback: both methods download the file in the browser.
• Platforms: iOS, Android and Web.

Compatibility

The plugin major version follows the Capacitor major version. New work targets Capacitor 8 first.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-file-sharer` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-file-sharer
bunx cap sync

Usage

import { FileSharer } from '@capgo/capacitor-file-sharer';

await FileSharer.share({
  filename: 'report.pdf',
  contentType: 'application/pdf',
  base64Data: reportBase64,
  title: 'Quarterly report',
  text: 'Attached report',
});

Share from a local file path or Capacitor file URL:

await FileSharer.share({
  filename: 'movie.mp4',
  contentType: 'video/mp4',
  path: fileUri,
});

Save directly on Android or download on Web:

const result = await FileSharer.save({
  filename: 'backup.zip',
  contentType: 'application/zip',
  base64Data: zipBase64,
  android: {
    saveDirectory: 'downloads',
    relativePath: 'Download/My App',
  },
});

console.log(result.uri);

Integration Notes

Android

• Sharing uses a FileProvider, ClipData, and URI grants so Android's chooser can read previews and thumbnails.
• share() resolves after the Android chooser opens. This avoids retaining large base64 payloads in activity state.
• save() writes to MediaStore on Android 10+ and to the matching public directory on older Android versions.
• Android 9 and below require WRITE_EXTERNAL_STORAGE for public saves; the plugin manifest includes it with maxSdkVersion=28.
• Android save directories: downloads, pictures, movies, music, and documents.

iOS

• share() supports base64Data and direct local path sharing.
• save() opens the native share sheet so the user can choose Save to Files or another destination.
• Swift Package Manager and CocoaPods are both supported.

Web

• share() and save() download the file in the browser.
• Base64 conversion is chunked to avoid large-array allocation failures in Chromium.

Error Codes

• ERR_PARAM_NO_FILENAME: filename is missing or blank.
• ERR_PARAM_NO_DATA: neither base64Data nor path was provided.
• ERR_PARAM_DATA_INVALID: base64 input could not be decoded.
• ERR_LOCAL_FILE_NOT_FOUND: the provided local path or content URI could not be opened.
• ERR_FILE_CACHING_FAILED: the native temporary file could not be written.
• ERR_FILE_SAVE_FAILED: Android could not save the file to public storage.
• ERR_ACTIVITY_NOT_FOUND: Android could not open a share target.
• USER_CANCELLED: iOS share sheet was dismissed without completing.

API

• share(...)
• save(...)
• getPluginVersion()
• Interfaces
• Type Aliases

Capacitor File Sharer plugin.

share(...)

share(options: ShareFileOptions) => Promise<void>

Share a file using the native share sheet on Android and iOS. On web, this downloads the file because browsers do not expose a consistent native file share target.

save(...)

save(options: SaveFileOptions) => Promise<SaveFileResult>

Save a file locally. On Android this writes to MediaStore/Downloads. On web this downloads the file. On iOS this opens the share sheet so the user can choose Save to Files or another target.

Returns: Promise<SaveFileResult>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

ShareFileOptions

Options used to share a file.

AndroidFileSharerOptions

Android-specific behavior for file sharing and saving.

SaveFileResult

Result returned by save().

PluginVersionResult

Plugin version payload.

Type Aliases

AndroidSaveDirectory

Android public collection used by save().

'downloads' | 'pictures' | 'movies' | 'music' | 'documents'

SaveFileOptions

Options used to save a file locally.

ShareFileOptions

Contributing

See CONTRIBUTING.md.

License

MPL-2.0