Capacitor Gallery Plus

A Capacitor plugin for accessing and managing media files (photos & videos) on iOS and Android. This plugin provides an easy way to retrieve media from the device's gallery, including metadata such as filenames, paths, and types.

Features

• 📸 Retrieve photos & videos from the device gallery
• 🏷️ Get metadata like filenames, paths, and MIME types
• 🚀 Works with Capacitor 5, 6, and 7
• 🔧 Simple API for easy integration

Install

npm install capacitor-gallery-plus
npx cap sync

iOS Setup

To ensure the plugin works correctly on iOS, you need to add the following permissions to your Info.plist file.

Required Permissions

Open your ios/App/App/Info.plist file and add the following keys inside the <dict> tag:

<key>NSPhotoLibraryUsageDescription</key>
<string>This app requires access to your photo library to display media files.</string>

This permission is required for accessing media files in the user's gallery.
If this is missing, the app might crash or fail to fetch media.

Requesting Permissions in Code

If you need to explicitly request permissions, you can call:

const permission = await GalleryPlus.checkPermissions();

if (permission.status !== "granted") {
    const request = await GalleryPlus.requestPermissions();

    if (request.status !== "granted") {
        console.error("Permission denied.");
    }
}

This ensures the app prompts the user for access when needed.

---

💡 Tip: If you experience crashes on iOS, check your Xcode logs to confirm missing permissions.

Usage

import { GalleryPlus } from 'capacitor-gallery-plus';

async function getMedia() {
    try {
        const result = await GalleryPlus.getMediaList({});
        console.log('Media files:', result.media);
    } catch (error) {
        console.error('Error retrieving media:', error);
    }
}

API

• checkPermissions()
• requestPermissions()
• getMediaList(...)
• getMedia(...)
• Interfaces
• Enums

checkPermissions()

checkPermissions() => Promise<{ status: string; }>

Checks the current permissions for accessing media.

Returns: Promise<{ status: string; }>

---

requestPermissions()

requestPermissions() => Promise<{ status: string; }>

Requests the necessary permissions to access media.

Returns: Promise<{ status: string; }>

---

getMediaList(...)

getMediaList(options: GetMediaListOptions) => Promise<{ media: MediaItem[]; }>

Retrieves media items from the device gallery.

Param	Type	Description
options	GetMediaListOptions	- The options for retrieving media.

Returns: Promise<{ media: MediaItem[]; }>

---

getMedia(...)

getMedia(options: GetMediaOptions) => Promise<FullMediaItem>

Retrieves details of a specific media item by its ID.

Param	Type
options	GetMediaOptions

Returns: Promise<FullMediaItem>

---

Interfaces

MediaItem

Prop	Type	Description
id	string	Unique identifier of the media item.
type	'image' | 'video'	The type of media (image or video).
createdAt	number	The Unix timestamp in milliseconds when the media was created.
thumbnail	string	Base64-encoded thumbnail image (only in getMediaList).
baseColor	string	Dominant color of the image (requires includeBaseColor).
name	string	Original file name of the media (only applicable for web platforms).
width	number	Width of the media in pixels (requires includeDetails).
height	number	Height of the media in pixels (requires includeDetails).
fileSize	number	Size of the file in bytes.
mimeType	string	The MIME type of the media item (e.g., "image/jpeg", "video/mp4").
isFavorite	boolean	Indicates whether the media item is marked as a favorite. (iOS-only)
isHidden	boolean	Indicates whether the media item is hidden. (iOS-only)
subtype	MediaSubtype	The subtype of the media, indicating special properties

GetMediaListOptions

Prop	Type	Description	Default
type	'image' | 'video' | 'all'	The type of media to retrieve. Default is "all". - "image": Only images - "video": Only videos - "all": Both images and videos	"all"
limit	number	The maximum number of media items to return.
startAt	number	The starting index for pagination.
thumbnailSize	number	The size of the thumbnail in pixels. Example: 200 for 200x200px.
sort	'oldest' | 'newest'	Sort order of the media items. - "oldest": Oldest first - "newest": Newest first	"newest"
includeDetails	boolean	Whether to include additional details like width, height.
includeBaseColor	boolean	Whether to extract and return the dominant color of the image.
filter	MediaFilter	Filter applied to the media selection

FullMediaItem

An extended version of MediaItem returned by getMedia.

Prop	Type	Description
path	string	File path or accessible URI of the media item.

GetMediaOptions

Prop	Type	Description	Default
id	string	The unique identifier of the media item.
includeDetails	boolean	Whether to include additional metadata such as width, height, and file size.	false
includeBaseColor	boolean	Whether to extract and return the dominant color of the image.	false
includePath	boolean	Whether to generate a temporary path to access the media. Available on iOS, Android, and Web. - On iOS & Android, the file path is only available if enabled. - On Web, the browser automatically provides a temporary URL.	false (iOS & Android), always available on Web

Enums

MediaSubtype

Members	Value	Description
MotionPhoto	"motion_photo"	A Live Photo (iOS) or Motion Photo (Android)
Panorama	"panorama"	A panorama image
HDR	"hdr"	A high dynamic range (HDR) image
Screenshot	"screenshot"	A screenshot
Portrait	"portrait"	A photo with depth effect (bokeh)
SlowMotion	"slow_motion"	A high frame rate slow-motion video
Timelapse	"timelapse"	A time-lapse video

MediaFilter

Members	Value	Description
All	"all"	No filtering, returns all media
Panorama	"panorama"	Only return panoramic images
HDR	"hdr"	Only return HDR images
Screenshot	"screenshot"	Only return screenshots

License

This project is dual-licensed under:

1. MIT License (Free & Open-Source) – For personal, educational, and open-source use.
2. Commercial License – Required for closed-source, proprietary, or commercial use.

See the LICENSE file for more details.