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.