@capgo/capacitor-photo-library

January 31, 2026 · View on GitHub

➡️ 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/

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

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.

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

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	❌
v5..	v5..	❌