@capgo/capacitor-photo-library

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

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'