Files and intents API
File selection, URL opening, and native file handoff.
internalPlugins.filePicker enables @capawesome/capacitor-file-picker@8.1.1. internalPlugins.intents enables @capacitor/app-launcher@8.0.1 and @capacitor-community/file-opener@8.0.1. Neither capability adds runtime permissions. Native pickers use system document UI.
File selection
pickFiles(options?) returns Effect<readonly PickedFile[], FilePickerError, Bridge | BrowserFiles>.
Prop
Type
PickedFile field | Type | Meaning |
|---|---|---|
name | string | File name, or the last URI segment when native name is missing. |
mimeType | string | Reported type, blob type, or application/octet-stream. |
size | number | Number of bytes in blob. |
lastModified | Optional number | Reported modification time. |
blob | Blob | Complete file contents in memory. |
uri | Optional string | Native URI. Absent for browser selections. |
| Picker error | Meaning |
|---|---|
Cancelled | Empty selection or cancellation |
Unavailable | Includes missing native paths |
BridgeError | Transport or schema failure |
filesLive(effect) provides BrowserFilesLive. BrowserFiles isolates picker and native-file reads. useFilePicker() exposes pick(options?), loading state, selected files, and errors.
External apps
openUrl(url) accepts a parseable URL and returns an Effect of void requiring Bridge | BrowserIntents. Native shells use the registered handler. Browsers open a new tab with noopener,noreferrer; blocked browser popups cannot be detected by this API.
openFile(file, options?) accepts OpenableFile with optional uri and mimeType. OpenFileOptions.chooser defaults to false. Browser calls and files without a native URI fail with Unavailable. Android's chooser and iOS Open In menu are selected by chooser: true. iOS's default is a Quick Look preview, which settles when the preview closes.
| Intent error | Meaning |
|---|---|
NoHandler | No app accepts operation; carries target |
Unavailable | Includes invalid URLs, missing files, browser file calls, or absent native URI |
BridgeError | Transport or schema failure |
intentsLive(effect) provides BrowserIntentsLive. BrowserIntents replaces browser URL opening. useIntent() exposes openUrl, openFile, and action state. Its success value is true.
Platform support
| Capability | Android | iOS | Browser |
|---|---|---|---|
| Picker | System document UI | System document UI | File input |
openFile default | Registered file handler | Quick Look; settles when closed | Unavailable |
chooser: true | System chooser | Open In menu | Unavailable |
openUrl | Registered URL handler | Registered URL handler | New tab with noopener,noreferrer; blocked popups undetectable |
Source: files implementation.