capacitor-gallery-plus v0.1.1

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.

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

getMedia(...)

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

Retrieves details of a specific media item by its ID.

Returns: Promise<FullMediaItem>

Interfaces

MediaItem

GetMediaListOptions

FullMediaItem

An extended version of MediaItem returned by getMedia.

GetMediaOptions

Enums

MediaSubtype

MediaFilter

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.