@capawesome/capacitor-file-picker

Capacitor plugin that allows the user to select a file.

Installation

npm install @capawesome/capacitor-file-picker
npx cap sync

Android

Permissions

This API requires the following permissions be added to your AndroidManifest.xml before or after the application tag:

<!-- Needed if you want to retrieve unredacted EXIF metadata from photos -->
<uses-permission android:name="android.permission.ACCESS_MEDIA_LOCATION" />
<!-- Needed if you want to read files from external storage -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-plugin-demo

Usage

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 pickFiles = async () => {
  const result = await FilePicker.pickFiles({
    types: ['image/png'],
  });
};

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(...)
• pickFiles(...)
• pickImages(...)
• pickMedia(...)
• pickVideos(...)
• requestPermissions(...)
• addListener('pickerDismissed', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permissions to access files.

Only available on Android.

Returns: Promise<PermissionStatus>

Since: 6.1.0

convertHeicToJpeg(...)

convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise<ConvertHeicToJpegResult>

Convert a HEIC image to JPEG.

Only available on iOS.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | ConvertHeicToJpegOptions |

Returns: Promise<ConvertHeicToJpegResult>

Since: 0.6.0

pickFiles(...)

pickFiles(options?: PickFilesOptions | undefined) => Promise<PickFilesResult>

Open the file picker that allows the user to select one or more files.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | PickFilesOptions |

Returns: Promise<PickFilesResult>

pickImages(...)

pickImages(options?: PickMediaOptions | undefined) => Promise<PickImagesResult>

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

pickMedia(...)

pickMedia(options?: PickMediaOptions | undefined) => Promise<PickMediaResult>

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

pickVideos(...)

pickVideos(options?: PickMediaOptions | undefined) => Promise<PickVideosResult>

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

requestPermissions(...)

requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>

Request permissions to access files.

Only available on Android.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | RequestPermissionsOptions |

Returns: Promise<PermissionStatus>

Since: 6.1.0

addListener('pickerDismissed', ...)

addListener(eventName: 'pickerDismissed', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when the file picker is dismissed.

Only available on iOS.

| Param | Type | | ------------------ | ------------------------------ | | eventName | 'pickerDismissed' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

Since: 0.6.2

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.6.2

Interfaces

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 | PermissionState | Permission state for reading external storage. On Android, this requests/checks the READ_EXTERNAL_STORAGE 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 |

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 | number | The duration of the video in seconds. Only available on Android and iOS. | 0.5.3 | | height | number | The height of the image or video in pixels. Only available on Android and iOS. | 0.5.3 | | mimeType | string | The mime type of the file. | | | modifiedAt | number | The last modified timestamp of the file in milliseconds. | 0.5.9 | | name | string | The name of the file. | | | path | string | The path of the file. Only available on Android and iOS. | | | size | number | The size of the file in bytes. | | | width | 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 | number | The maximum number of files that the user can select. Setting this to 0 sets the selection limit to unlimited. Currently, only 0 and 1 are supported. | 0 | 6.0.0 | | readData | boolean | Whether to read the file data. | false | |

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. | 0 | 5.2.0 | | ordered | 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> |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

PickImagesOptions

PickMediaOptions

PickImagesResult

PickMediaResult

PickMediaResult

PickFilesResult

PickVideosOptions

PickMediaOptions

PickVideosResult

PickMediaResult

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!