@capgo/capacitor-file-sharer

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

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.

| 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. |

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