@capgo/capacitor-file-sharer

June 16, 2026 · View on GitHub

Get instant updates for your app with Capgo

Missing a feature? We will build the plugin for you

Capacitor plugin for sharing and saving files on Android, iOS, and Web.

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	Yes
v7..	v7..	On demand
v6..	v6..	On demand

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.

Capacitor File Sharer plugin.

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.

Param	Type
`options`	`ShareFileOptions`

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.

Param	Type
`options`	`ShareFileOptions`

Returns: Promise<SaveFileResult>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

ShareFileOptions

Options used to share a file.

Prop	Type	Description
`filename`	`string`	File name presented to the receiving app. Include the extension.
`base64Data`	`string`	Base64 encoded file data. Data URL prefixes are accepted.
`path`	`string`	Local file path, file:// URL, content:// URL, or Capacitor capacitor_file URL.
`contentType`	`string`	MIME type of the file. Defaults to application/octet-stream when omitted.
`text`	`string`	Optional text or caption shared with the file.
`title`	`string`	Optional title for the share sheet or shared item.
`subject`	`string`	Optional subject used by mail and compatible share targets.
`android`	`AndroidFileSharerOptions`	Android-specific options.

AndroidFileSharerOptions

Android-specific behavior for file sharing and saving.

Prop	Type	Description
`chooserTitle`	`string`	Title shown at the top of the Android chooser.
`saveDirectory`	`AndroidSaveDirectory`	Public collection used by save(). Defaults from contentType.
`relativePath`	`string`	Optional relative folder inside the selected public collection on Android 10+.

SaveFileResult

Result returned by save().

Prop	Type	Description
`uri`	`string`	Native URI of the saved file when the platform provides one.

PluginVersionResult

Plugin version payload.

Prop	Type	Description
`version`	`string`	Version identifier returned by the platform implementation.