https://github.com/Cap-go/capacitor-photo-library
Capacitor plugin Displays photo gallery as web page, or boring native screen which you cannot modify but require no authorization
https://github.com/Cap-go/capacitor-photo-library
capacitor plugin
Last synced: 4 months ago
JSON representation
Capacitor plugin Displays photo gallery as web page, or boring native screen which you cannot modify but require no authorization
- Host: GitHub
- URL: https://github.com/Cap-go/capacitor-photo-library
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-10-03T09:47:09.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-01-28T17:43:35.000Z (4 months ago)
- Last Synced: 2026-01-29T07:37:14.692Z (4 months ago)
- Topics: capacitor, plugin
- Language: Java
- Homepage: https://capgo.app
- Size: 673 KB
- Stars: 4
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-capacitor - Photo Library - Display photo gallery as web page or native screen. ([Capgo plugins](https://capgo.app/) / Camera & Media)
- awesome-ionic - capacitor-photo-library - Capacitor plugin Displays photo gallery as web page, or boring native screen which you cannot modify but require no authorization. (Capgo Capacitor Plugins)
README
# @capgo/capacitor-photo-library
Displays photo gallery as web page, or boring native screen which you cannot modify but require no authorization
## Documentation
The most complete doc is available here: https://capgo.app/docs/plugins/photo-library/
## Compatibility
| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\*.\* | v8.\*.\* | ✅ |
| v7.\*.\* | v7.\*.\* | On demand |
| v6.\*.\* | v6.\*.\* | ❌ |
| v5.\*.\* | v5.\*.\* | ❌ |
> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
## Install
```bash
npm install @capgo/capacitor-photo-library
npx cap sync
```
## Usage
```ts
import { Capacitor } from '@capacitor/core';
import { PhotoLibrary } from '@capgo/capacitor-photo-library';
const { state } = await PhotoLibrary.requestAuthorization();
if (state === 'authorized' || state === 'limited') {
const { assets, hasMore } = await PhotoLibrary.getLibrary({
limit: 100,
thumbnailWidth: 256,
thumbnailHeight: 256,
});
const gallery = assets.map(asset => ({
id: asset.id,
fileName: asset.fileName,
thumbnailUrl: asset.thumbnail
? asset.thumbnail.webPath ?? Capacitor.convertFileSrc(asset.thumbnail.path)
: undefined,
photoUrl: asset.file
? asset.file.webPath ?? Capacitor.convertFileSrc(asset.file.path)
: undefined,
}));
console.log('Loaded', gallery.length, 'items. More available?', hasMore);
}
const picked = await PhotoLibrary.pickMedia({
selectionLimit: 3,
includeVideos: true,
});
console.log('User selected', picked.assets.length, 'items');
```
The native implementations cache exported files inside the application cache
directory. You can safely delete the `photoLibrary` folder under the cache if
you need to free up space.
## API
* [`checkAuthorization()`](#checkauthorization)
* [`requestAuthorization()`](#requestauthorization)
* [`getAlbums()`](#getalbums)
* [`getLibrary(...)`](#getlibrary)
* [`getPhotoUrl(...)`](#getphotourl)
* [`getThumbnailUrl(...)`](#getthumbnailurl)
* [`pickMedia(...)`](#pickmedia)
* [`getPluginVersion()`](#getpluginversion)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
### checkAuthorization()
```typescript
checkAuthorization() => Promise<{ state: PhotoLibraryAuthorizationState; }>
```
Returns the current authorization status without prompting the user.
**Returns:** Promise<{ state: PhotoLibraryAuthorizationState; }>
--------------------
### requestAuthorization()
```typescript
requestAuthorization() => Promise<{ state: PhotoLibraryAuthorizationState; }>
```
Requests access to the photo library if needed.
**Returns:** Promise<{ state: PhotoLibraryAuthorizationState; }>
--------------------
### getAlbums()
```typescript
getAlbums() => Promise<{ albums: PhotoLibraryAlbum[]; }>
```
Retrieves the available albums.
**Returns:** Promise<{ albums: PhotoLibraryAlbum[]; }>
--------------------
### getLibrary(...)
```typescript
getLibrary(options?: GetLibraryOptions | undefined) => Promise
```
Retrieves library assets along with URLs that can be displayed in the web view.
| Param | Type |
| ------------- | --------------------------------------------------------------- |
| **`options`** | GetLibraryOptions |
**Returns:** Promise<GetLibraryResult>
--------------------
### getPhotoUrl(...)
```typescript
getPhotoUrl(options: { id: string; }) => Promise
```
Retrieves a displayable URL for the full resolution version of the asset.
If you already called `getLibrary` with `includeFullResolutionData`, you normally
do not need this method.
| Param | Type |
| ------------- | ---------------------------- |
| **`options`** | { id: string; } |
**Returns:** Promise<PhotoLibraryFile>
--------------------
### getThumbnailUrl(...)
```typescript
getThumbnailUrl(options: { id: string; width?: number; height?: number; quality?: number; }) => Promise
```
Retrieves a displayable URL for a resized thumbnail of the asset.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------- |
| **`options`** | { id: string; width?: number; height?: number; quality?: number; } |
**Returns:** Promise<PhotoLibraryFile>
--------------------
### pickMedia(...)
```typescript
pickMedia(options?: PickMediaOptions | undefined) => Promise
```
Opens the native system picker so the user can select media without granting full photo library access.
The selected files are copied into the application cache and returned with portable URLs.
| Param | Type |
| ------------- | ------------------------------------------------------------- |
| **`options`** | PickMediaOptions |
**Returns:** Promise<PickMediaResult>
--------------------
### getPluginVersion()
```typescript
getPluginVersion() => Promise<{ version: string; }>
```
Get the native Capacitor plugin version
**Returns:** Promise<{ version: string; }>
--------------------
### Interfaces
#### PhotoLibraryAlbum
| Prop | Type |
| ---------------- | ------------------- |
| **`id`** | string |
| **`title`** | string |
| **`assetCount`** | number |
#### GetLibraryResult
| Prop | Type | Description |
| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **`assets`** | PhotoLibraryAsset[] | |
| **`totalCount`** | number | Total number of assets matching the query in the library. `assets.length` can be less than this value when pagination is used. |
| **`hasMore`** | boolean | Whether more assets are available when using pagination. |
#### PhotoLibraryAsset
| Prop | Type | Description |
| ---------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **`id`** | string | |
| **`fileName`** | string | |
| **`type`** | PhotoAssetType | |
| **`width`** | number | |
| **`height`** | number | |
| **`duration`** | number | |
| **`creationDate`** | string | |
| **`modificationDate`** | string | |
| **`latitude`** | number | |
| **`longitude`** | number | |
| **`mimeType`** | string | |
| **`size`** | number | Size in bytes reported by the OS for the underlying asset, if available. |
| **`albumIds`** | string[] | |
| **`thumbnail`** | PhotoLibraryFile | |
| **`file`** | PhotoLibraryFile | |
#### PhotoLibraryFile
| Prop | Type | Description |
| -------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| **`path`** | string | Absolute path on the native file system. |
| **`webPath`** | string | URL that can be used inside a web view. Usually produced by `Capacitor.convertFileSrc(path)`. |
| **`mimeType`** | string | |
| **`size`** | number | Size in bytes if known, otherwise `-1`. |
#### GetLibraryOptions
| Prop | Type | Description |
| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
| **`offset`** | number | Number of assets to skip from the beginning of the query. |
| **`limit`** | number | Maximum number of assets to return. Omit to return everything that matches. |
| **`includeImages`** | boolean | Include images in the result. Defaults to `true`. |
| **`includeVideos`** | boolean | Include videos in the result. Defaults to `false`. |
| **`includeAlbumData`** | boolean | Include information about the albums each asset belongs to. Defaults to `false`. |
| **`includeCloudData`** | boolean | Include assets stored in the cloud (iCloud / Google Photos). Defaults to `true`. |
| **`useOriginalFileNames`** | boolean | If `true`, use the original filenames reported by the OS when available. |
| **`thumbnailWidth`** | number | Width of the generated thumbnails. Defaults to `512`. |
| **`thumbnailHeight`** | number | Height of the generated thumbnails. Defaults to `384`. |
| **`thumbnailQuality`** | number | JPEG quality for generated thumbnails (0-1). Defaults to `0.5`. |
| **`includeFullResolutionData`** | boolean | When `true`, copies the full sized asset into the app cache and returns its URL. Defaults to `false`. |
#### PickMediaResult
| Prop | Type |
| ------------ | -------------------------------- |
| **`assets`** | PhotoLibraryAsset[] |
#### PickMediaOptions
| Prop | Type | Description |
| ---------------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
| **`selectionLimit`** | number | Maximum number of items the user can select. Use `0` to allow unlimited selection. Defaults to `1`. |
| **`includeImages`** | boolean | Allow the user to select images. Defaults to `true`. |
| **`includeVideos`** | boolean | Allow the user to select videos. Defaults to `false`. |
| **`thumbnailWidth`** | number | Width of the generated thumbnails for picked items. Defaults to `256`. |
| **`thumbnailHeight`** | number | Height of the generated thumbnails for picked items. Defaults to `256`. |
| **`thumbnailQuality`** | number | JPEG quality for generated thumbnails (0-1). Defaults to `0.7`. |
### Type Aliases
#### PhotoLibraryAuthorizationState
'authorized' | 'limited' | 'denied' | 'notDetermined'
#### PhotoAssetType
'image' | 'video'