@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 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();
};

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>

pickDirectory()¶

pickDirectory() => Promise<PickDirectoryResult>

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

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`

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

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!

@capawesome/capacitor-file-picker¶

Installation¶

Android¶

Permissions¶

Configuration¶

Demo¶

Usage¶

API¶

checkPermissions()¶

convertHeicToJpeg(...)¶

pickFiles(...)¶

pickDirectory()¶

pickImages(...)¶

pickMedia(...)¶

pickVideos(...)¶

requestPermissions(...)¶

addListener('pickerDismissed', ...)¶

removeAllListeners()¶

Interfaces¶

PermissionStatus¶

ConvertHeicToJpegResult¶

ConvertHeicToJpegOptions¶

PickFilesResult¶

PickedFile¶

PickFilesOptions¶

PickDirectoryResult¶

PickMediaOptions¶

RequestPermissionsOptions¶

PluginListenerHandle¶

Type Aliases¶

PermissionState¶

PickImagesOptions¶

PickImagesResult¶

PickMediaResult¶

PickVideosOptions¶

PickVideosResult¶

PermissionType¶

Changelog¶

License¶

Credits¶