@capawesome/capacitor-file-picker
v7.0.0-dev.1765885034TypeScript
Capacitor plugin that allows the user to select a file.
40.4K/weekUpdated 2 weeks agoMITUnpacked: 157.1 KB
Published by Robin Genz
npm install @capawesome/capacitor-file-picker@capawesome/capacitor-file-picker
Capacitor plugin that allows the user to select a file, directory, image, or video from the device's file system or gallery.
Features
We are proud to offer one of the most complete and feature-rich Capacitor plugins for file picking. Here are some of the key features:
- 🖥️ Cross-platform: Supports Android, iOS and Web.
- 📂 Directory picking: Allows users to select a directory to retrieve all files.
- 🖼️ Image picking: Lets users select one or more images from the gallery.
- 🎥 Video picking: Lets users select one or more videos from the gallery.
- 📄 File picking: Lets users select one or more miscellaneous files from the file system.
- 📸 HEIC to JPEG conversion: Converts HEIC images to JPEG format on iOS.
- 📜 File metadata: Retrieves metadata such as file size, name, mime type, and last modified timestamp.
- 📦 SPM: Supports Swift Package Manager for iOS.
- 🔁 Up-to-date: Always supports the latest Capacitor version.
Missing a feature? Just open an issue and we'll take a look!
Newsletter
Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.
Compatibility
| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | >=8.x.x | Active support |
| 6.x.x | 6.x.x | Deprecated |
| 5.x.x | 5.x.x | Deprecated |
Installation
``bash`
npm install @capawesome/capacitor-file-picker
npx cap sync
$3
#### Permissions
This API requires the following permissions be added to your AndroidManifest.xml before or after the application tag:
`xml`
$3
#### Entitlements
To use this plugin with Mac Catalyst, your app must have the com.apple.security.files.user-selected.read-only entitlement enabled. This allows the app to read files selected by the user. Check out the Apple documentation for more information.
`xml`
If you don't want to use the plugin with Mac Catalyst, you can skip this step.
Configuration
No configuration required for this plugin.
Usage
`typescript
import { FilePicker } from '@capawesome/capacitor-file-picker';
const appendFileToFormData = async () => {
const result = await FilePicker.pickFiles();
const file = result.files[0];
const formData = new FormData();
if (file.blob) {
const rawFile = new File(file.blob, file.name, {
type: file.mimeType,
});
formData.append('file', rawFile, file.name);
}
};
const checkPermissions = async () => {
const result = await FilePicker.checkPermissions();
};
const copyFile = async () => {
const result = await FilePicker.copyFile({
from: 'path/to/file',
to: 'path/to/destination',
});
};
const pickFiles = async () => {
const result = await FilePicker.pickFiles({
types: ['image/png'],
});
};
const pickDirectory = async () => {
const result = await FilePicker.pickDirectory();
};
const pickImages = async () => {
const result = await FilePicker.pickImages();
};
const pickMedia = async () => {
const result = await FilePicker.pickMedia();
};
const pickVideos = async () => {
const result = await FilePicker.pickVideos();
};
const requestPermissions = async () => {
const result = await FilePicker.requestPermissions();
};
`
API
* checkPermissions()
* convertHeicToJpeg(...)
* copyFile(...)
* pickFiles(...)
* pickDirectory()
* pickImages(...)
* pickMedia(...)
* pickVideos(...)
* requestPermissions(...)
* addListener('pickerDismissed', ...)
* removeAllListeners()
* Interfaces
* Type Aliases
$3
`typescript`
checkPermissions() => Promise
Check permissions to access files.
Only available on Android.
Returns: Promise<PermissionStatus>
Since: 6.1.0
--------------------
$3
`typescript`
convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise
Convert a HEIC image to JPEG.
Only available on iOS.
| Param | Type |
| ------------- | ----------------------------------------------------------------------------- |
| options | ConvertHeicToJpegOptions |
Returns: Promise<ConvertHeicToJpegResult>
Since: 0.6.0
--------------------
$3
`typescript`
copyFile(options: CopyFileOptions) => Promise
Copy a file to a new location.
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| options | CopyFileOptions |
Since: 7.1.0
--------------------
$3
`typescript`
pickFiles(options?: PickFilesOptions | undefined) => Promise
Open the file picker that allows the user to select one or more files.
| Param | Type |
| ------------- | ------------------------------------------------------------- |
| options | PickFilesOptions |
Returns: Promise<PickFilesResult>
--------------------
$3
`typescript`
pickDirectory() => Promise
Open a picker dialog that allows the user to select a directory.
Only available on Android and iOS.
Returns: Promise<PickDirectoryResult>
Since: 6.2.0
--------------------
$3
`typescript`
pickImages(options?: PickMediaOptions | undefined) => Promise
Pick one or more images from the gallery.
On iOS 13 and older it only allows to pick one image.
Only available on Android and iOS.
| Param | Type |
| ------------- | ------------------------------------------------------------- |
| options | PickMediaOptions |
Returns: Promise<PickFilesResult>
Since: 0.5.3
--------------------
$3
`typescript`
pickMedia(options?: PickMediaOptions | undefined) => Promise
Pick one or more images or videos from the gallery.
On iOS 13 and older it only allows to pick one image or video.
Only available on Android and iOS.
| Param | Type |
| ------------- | ------------------------------------------------------------- |
| options | PickMediaOptions |
Returns: Promise<PickFilesResult>
Since: 0.5.3
--------------------
$3
`typescript`
pickVideos(options?: PickMediaOptions | undefined) => Promise
Pick one or more videos from the gallery.
On iOS 13 and older it only allows to pick one video.
Only available on Android and iOS.
| Param | Type |
| ------------- | ------------------------------------------------------------- |
| options | PickMediaOptions |
Returns: Promise<PickFilesResult>
Since: 0.5.3
--------------------
$3
`typescript`
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise
Request permissions to access files.
Only available on Android.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------- |
| options | RequestPermissionsOptions |
Returns: Promise<PermissionStatus>
Since: 6.1.0
--------------------
$3
`typescript`
addListener(eventName: 'pickerDismissed', listenerFunc: () => void) => Promise
Called when the file picker is dismissed.
Only available on iOS.
| Param | Type |
| ------------------ | ------------------------------ |
| eventName | 'pickerDismissed' |
| listenerFunc | () => void |
Returns: Promise<PluginListenerHandle>
Since: 0.6.2
--------------------
$3
`typescript`
removeAllListeners() => Promise
Remove all listeners for this plugin.
Since: 0.6.2
--------------------
$3
#### PermissionStatus
| Prop | Type | Description | Since |
| ------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----- |
| accessMediaLocation | PermissionState | Permission state for accessing media location. On Android, this requests/checks the ACCESS_MEDIA_LOCATION permission. | 6.1.0 |readExternalStorage
| | READ_EXTERNAL_STORAGEPermissionState | Permission state for reading external storage. On Android, this requests/checks the permission. | 6.1.0 |
#### ConvertHeicToJpegResult
| Prop | Type | Description | Since |
| ---------- | ------------------- | ------------------------------------- | ----- |
| path | string | The path of the converted JPEG image. | 0.6.0 |
#### ConvertHeicToJpegOptions
| Prop | Type | Description | Since |
| ---------- | ------------------- | --------------------------- | ----- |
| path | string | The path of the HEIC image. | 0.6.0 |
#### CopyFileOptions
| Prop | Type | Description | Default | Since |
| --------------- | -------------------- | --------------------------------------------------------------- | ----------------- | ----- |
| from | string | The path of the file to copy. | | 7.1.0 |
| overwrite | boolean | Whether to overwrite if the file at destination already exists. | true | 7.2.0 |
| to | string | The path to copy the file to. | | 7.1.0 |
#### PickFilesResult
| Prop | Type |
| ----------- | ------------------------- |
| files | PickedFile[] |
#### PickedFile
| Prop | Type | Description | Since |
| ---------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- | ----- |
| blob | Blob | The Blob instance of the file. Only available on Web. | |
| data | string | The Base64 string representation of the data contained in the file. Is only provided if readData is set to true. | |duration
| | heightnumber | The duration of the video in seconds. Only available on Android and iOS. | 0.5.3 |
| | mimeTypenumber | The height of the image or video in pixels. Only available on Android and iOS. | 0.5.3 |
| | modifiedAtstring | The mime type of the file. | |
| | namenumber | The last modified timestamp of the file in milliseconds. | 0.5.9 |
| | pathstring | The name of the file. | |
| | sizestring | The path of the file. Only available on Android and iOS. | |
| | widthnumber | The size of the file in bytes. | |
| | number | The width of the image or video in pixels. Only available on Android and iOS. | 0.5.3 |
#### PickFilesOptions
| Prop | Type | Description | Default | Since |
| -------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| types | string[] | List of accepted file types. Look at IANA Media Types for a complete list of standard media types. This option is ignored if limit is set. | | |limit
| | 0number | The maximum number of files that the user can select. Setting this to sets the selection limit to unlimited. Currently, only 0 and 1 are supported. | readData0 | 6.0.0 |
| | boolean | Whether to read the file data. Attention: Reading large files can lead to app crashes. It's therefore not recommended to use this option. Instead, use the fetch API to load the file as a blob, see this example. | false | |
#### PickDirectoryResult
| Prop | Type | Description | Since |
| ---------- | ------------------- | ----------------------------------- | ----- |
| path | string | The path to the selected directory. | 6.2.0 |
#### PickMediaOptions
| Prop | Type | Description | Default | Since |
| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| readData | boolean | Whether to read the file data. | false | |
| skipTranscoding | boolean | Whether to avoid transcoding, if possible. On iOS, for example, HEIC images are automatically transcoded to JPEG. Only available on iOS. | true | |
| limit | number | The maximum number of files that the user can select. Setting this to 0 sets the selection limit to unlimited. On Android and Web, only 0 and 1 are supported. | ordered0 | 5.2.0 |
| | boolean | Whether an ordered number is displayed instead of a check mark in the selection badge. Only available on iOS (15+). | false | 5.3.0 |
#### RequestPermissionsOptions
| Prop | Type | Description | Default | Since |
| ----------------- | ----------------------------- | --------------------------- | ----------------------------------------------------------- | ----- |
| permissions | PermissionType[] | The permissions to request. | ["accessMediaLocation", "readExternalStorage"] | 6.1.0 |
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| remove` | () => Promise<void> |
$3
#### PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
#### PickImagesOptions
#### PickImagesResult
#### PickMediaResult
#### PickVideosOptions
#### PickVideosResult
#### PermissionType
'accessMediaLocation' | 'readExternalStorage'
Changelog
See CHANGELOG.md.
License
See LICENSE.
Credits
This plugin is based on the Capacitor File Picker plugin.
Thanks to everyone who contributed to the project!