https://github.com/jonz94/capacitor-image-picker
⚡️ Capacitor plugin for multiple image selection.
https://github.com/jonz94/capacitor-image-picker
android capacitor capacitor-android capacitor-ios capacitor-plugin image-picker ios
Last synced: over 1 year ago
JSON representation
⚡️ Capacitor plugin for multiple image selection.
- Host: GitHub
- URL: https://github.com/jonz94/capacitor-image-picker
- Owner: jonz94
- License: 0bsd
- Created: 2022-10-08T00:25:11.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-22T05:40:34.000Z (over 1 year ago)
- Last Synced: 2025-03-14T20:51:15.969Z (over 1 year ago)
- Topics: android, capacitor, capacitor-android, capacitor-ios, capacitor-plugin, image-picker, ios
- Language: Java
- Homepage: https://www.npmjs.com/package/@jonz94/capacitor-image-picker
- Size: 688 KB
- Stars: 14
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Image Picker
@jonz94/capacitor-image-picker
Capacitor plugin for multiple image selection.
## Install
```bash
npm install @jonz94/capacitor-image-picker
npx cap sync
```
## iOS
### Native Dependencies Setup
This plugin uses [a forked version](https://github.com/jonz94/YPImagePicker) of [YPImagePicker](https://github.com/Yummypets/YPImagePicker) under the hood.
In order to use this plugin, you need to manually modified `ios/App/Podfile` as following:
```diff
target 'App' do
capacitor_pods
# Add your Pods here
+ pod 'YPImagePicker', :git => 'https://github.com/jonz94/YPImagePicker.git', :tag => '5.2.2.0'
end
```
After modified `ios/App/Podfile`, make sure to run `pod update` command to sync up the iOS project.
### Permissions
iOS requires the following usage description be added and filled out for your app in `Info.plist`:
- `NSPhotoLibraryUsageDescription` (`Privacy - Photo Library Usage Description`)
Read about [Configuring `Info.plist`](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist) in the [iOS Guide](https://capacitorjs.com/docs/ios) for more information on setting iOS permissions in Xcode.
## Android
### Native Dependencies Setup
This plugin uses [a forked version](https://github.com/jonz94/TedImagePicker) of [TedImagePicker](https://github.com/ParkSangGwon/TedImagePicker) under the hood.
#### Setup [JitPack](https://jitpack.io) Repository
Add following line to your `android/build.gradle`:
```diff
allprojects {
repositories {
google()
mavenCentral()
+ maven { url "https://jitpack.io" }
}
}
```
#### Enable Data Binding
Add following lines to your `android/app/build.gradle`:
```diff
android {
compileSdkVersion rootProject.ext.compileSdkVersion
defaultConfig {
// ...
}
buildTypes {
// ...
}
+ dataBinding {
+ enabled true
+ }
}
```
#### Sync Project
After modified `android/build.gradle` and `android/app/build.gradle`, make sure to run `Sync Project with Gradle Files` in Android Studio.
### Permissions
This plugin requires the following permissions be added to your `AndroidManifest.xml`:
```xml
```
The storage permissions are for reading photo files.
Read about [Setting Permissions](https://capacitorjs.com/docs/android/configuration#setting-permissions) in the [Android Guide](https://capacitorjs.com/docs/android) for more information on setting Android permissions.
## Configuration
No configuration required for this plugin.
## Usage
```typescript
import { ImagePicker } from '@jonz94/capacitor-image-picker';
const pickSingleImage = async () => {
const { images } = await ImagePicker.present();
// console.log(images[0]);
return images[0];
}
const pickMultipleImages = async () => {
const { images } = await ImagePicker.present({ limit: 10 });
// console.log(images);
return images;
}
const pickMultipleImagesWithCustomText = async () => {
const { images } = await ImagePicker.present({
limit: 10,
surpassLimitMessage: 'You cannot select more than %d images.',
titleText: 'Pick a image',
albumsTitleText: 'Chose an album',
libraryTitleText: 'Click here to change library',
cancelText: 'Go Back',
doneText: 'OK',
});
// console.log(images);
return images;
}
```
## API
* [`present(...)`](#present)
* [Interfaces](#interfaces)
### present(...)
```typescript
present(options?: PresentOptions | undefined) => Promise
```
| Param | Type |
| ------------- | --------------------------------------------------------- |
| **`options`** | PresentOptions |
**Returns:** Promise<Images>
--------------------
### Interfaces
#### Images
| Prop | Type | Description | Since |
| ------------ | -------------------- | ------------------------------- | ----- |
| **`images`** | Image[] | Array of all the picked images. | 1.0.0 |
#### Image
| Prop | Type | Description | Since |
| -------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------- | ----- |
| **`path`** | string | The file path of the image. | 1.0.0 |
| **`webPath`** | string | webPath returns a path that can be used to set the src attribute of an image for efficient loading and rendering. | 1.0.0 |
| **`mimeType`** | string | The mime type of the image. | 1.0.0 |
#### PresentOptions
| Prop | Type | Description | Default | Since |
| ------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ----- |
| **`limit`** | number | Maximum number of images the user will be able to choose. Note: If this is set to 1, upon selection of a single image. | 1 | 1.0.0 |
| **`surpassLimitMessage`** | string | The message when user select more than maximum number of pictures. This message will not occur when `limit` is 1. Note: The message **MUST INCLUDE ONE AND ONLY ONE `%d`** as a placeholder for showing the value of `limit`. | "You can only select %d images." | 1.0.0 |
| **`titleText`** | string | Android only: The title of the image picker. | "Select Image" | 1.0.0 |
| **`albumAllText`** | string | Android only: name of the all photos album. | "All" | 1.2.0 |
| **`libraryTitleText`** | string | iOS only: The title of the library. | "Library" | 1.0.0 |
| **`albumsTitleText`** | string | iOS only: The title of the albums. | "Albums" | 1.0.0 |
| **`cancelText`** | string | iOS only: The text to display on the cancel button. Note: on Android, the cancel button is shown as icon-only back button with no text. | "Cancel" | 1.0.0 |
| **`doneText`** | string | The text to display on the done button. | "Done" | 1.0.0 |
## Changelog
See [CHANGELOG.md](https://github.com/jonz94/capacitor-image-picker/blob/main/CHANGELOG.md).
## License
See [LICENSE](https://github.com/jonz94/capacitor-image-picker/blob/main/LICENSE).
## Credits
- [EinfachHans's Advanced ImagePicker Cordova Plugin](https://github.com/EinfachHans/cordova-plugin-advanced-imagepicker) inspires this Capacitor plugin.
- [YPImagePicker](https://github.com/Yummypets/YPImagePicker) provides iOS implementation.
- [TedImagePicker](https://github.com/ParkSangGwon/TedImagePicker) provides Android implementation.
- [Official Capacitor Camera Plugin](https://github.com/ionic-team/capacitor-plugins/blob/%40capacitor/camera%404.1.2/camera/ios/Plugin/CameraPlugin.swift#L518-L527) provides `saveTemporaryImage()` implementation on iOS.
- [Capawesome's Capacitor File Picker Plugin](https://github.com/capawesome-team/capacitor-file-picker/blob/v0.5.1/ios/Plugin/FilePicker.swift#L37-L46) provides `getMimeTypeFromURL()` implementation on iOS.