@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/

Install

npm install @capgo/capacitor-photo-library
npx cap sync

Usage

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()
• requestAuthorization()
• getAlbums()
• getLibrary(...)
• getPhotoUrl(...)
• getThumbnailUrl(...)
• pickMedia(...)
• getPluginVersion()
• Interfaces
• Type Aliases

checkAuthorization()

checkAuthorization() => Promise<{ state: PhotoLibraryAuthorizationState; }>

Returns the current authorization status without prompting the user.

Returns: Promise<{ state: PhotoLibraryAuthorizationState; }>

requestAuthorization()

requestAuthorization() => Promise<{ state: PhotoLibraryAuthorizationState; }>

Requests access to the photo library if needed.

Returns: Promise<{ state: PhotoLibraryAuthorizationState; }>

getAlbums()

getAlbums() => Promise<{ albums: PhotoLibraryAlbum[]; }>

Retrieves the available albums.

Returns: Promise<{ albums: PhotoLibraryAlbum[]; }>

getLibrary(...)

getLibrary(options?: GetLibraryOptions | undefined) => Promise<GetLibraryResult>

Retrieves library assets along with URLs that can be displayed in the web view.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | GetLibraryOptions |

Returns: Promise<GetLibraryResult>

getPhotoUrl(...)

getPhotoUrl(options: { id: string; }) => Promise<PhotoLibraryFile>

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(...)

getThumbnailUrl(options: { id: string; width?: number; height?: number; quality?: number; }) => Promise<PhotoLibraryFile>

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(...)

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

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()

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'