README

Display images (jpg, jpeg, png, heic) in a full-screen native lightbox overlay above the running app UI.

Features

Native full-screen modal on both iOS and Android
Pinch-to-zoom (up to 5×) and pan after zooming
Aspect-fit display by default
Loads local file paths and remote URLs (with WebView session cookie injection for authenticated endpoints)
Optional Edit, Markup, Share, and Delete action buttons
Native share sheet for both local files and remote images
EditPressed, MarkupPressed, DeletePressed, and ClosePressed events with imageId payload
Icon-based toolbar at the top of the screen with dark-background buttons for legibility
Safe-area aware controls; dismiss animation
Graceful error states (invalid URL, missing file, decode failure)

Installation

# 1. Install the package
composer require pteal79/plugin-image-lightbox

# 2. Publish the plugins provider (first time only)
php artisan vendor:publish --tag=nativephp-plugins-provider

# 3. Register the plugin (adds the service provider to NativePluginsServiceProvider)
php artisan native:plugin:register pteal79/plugin-image-lightbox

# 4. Verify registration
php artisan native:plugin:list

Local development (path repository)

Add to your app's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/pteal79/plugin-image-lightbox"
        }
    ]
}

Then run composer require pteal79/plugin-image-lightbox.

Requirements

Android

Requirement	Detail
Permission	`android.permission.INTERNET` (remote URLs) — added automatically via `nativephp.json`
FileProvider	The host app must have a `FileProvider` configured with authority `${applicationId}.provider` for the Share feature to work. NativePHP Mobile typically configures this by default.
HEIC support	Android 9 (API 28)+ via `ImageDecoder`. Older devices fall back to `BitmapFactory`; HEIC may not decode on API < 28.

iOS

No additional permissions or Info.plist entries are required. HEIC is supported natively via UIImage.

Usage

PHP — Livewire / Blade

use Nativephp\ImageLightbox\Facades\ImageLightbox;

// Remote URL — minimal
ImageLightbox::show([
    'url' => 'https://example.com/photo.jpg',
]);

// Local file — minimal
ImageLightbox::show([
    'local' => '/var/mobile/.../Documents/app/storage/app/public/photo.jpg',
]);

// Full options
ImageLightbox::show([
    'url'     => 'https://example.com/photo.heic',
    'imageId' => '550e8400-e29b-41d4-a716-446655440000',
    'edit'    => true,
    'markup'  => true,
    'share'   => true,
    'delete'  => true,
]);

Parameters

Parameter	Type	Default	Description
`url`	`string`	`null`	Remote image URL (`http`/`https`). Supported formats: `jpg`, `jpeg`, `png`, `heic`, `webp`.
`local`	`string`	`null`	Absolute local file path to an image on the device.
`imageId`	`string`	`null`	Optional identifier included in all event payloads.
`edit`	`bool`	`false`	Show an Edit button in the toolbar.
`markup`	`bool`	`false`	Show a Markup button in the toolbar.
`share`	`bool`	`false`	Show a Share button that opens the native share sheet.
`delete`	`bool`	`false`	Show a Delete button in the toolbar.

Either url or local is required. If neither is provided the call is a no-op.

Events

All events are dispatched after the lightbox has dismissed. Each event carries the imageId that was passed to ::show() (or null if none was provided).

`ClosePressed`

Fired when the user taps the close (✕) button.

use Native\Mobile\Attributes\OnNative;
use Pteal79\ImageLightbox\Events\ClosePressed;

#[OnNative(ClosePressed::class)]
public function handleClose(?string $imageId = null): void
{
    // lightbox has been dismissed
}

`EditPressed`

Fired when the user taps the Edit button (only available when edit: true).

use Native\Mobile\Attributes\OnNative;
use Pteal79\ImageLightbox\Events\EditPressed;

#[OnNative(EditPressed::class)]
public function handleEdit(?string $imageId = null): void
{
    // open your edit UI here
}

`MarkupPressed`

Fired when the user taps the Markup button (only available when markup: true).

use Native\Mobile\Attributes\OnNative;
use Pteal79\ImageLightbox\Events\MarkupPressed;

#[OnNative(MarkupPressed::class)]
public function handleMarkup(?string $imageId = null): void
{
    //
}

`DeletePressed`

Fired when the user taps the Delete button (only available when delete: true).

use Native\Mobile\Attributes\OnNative;
use Pteal79\ImageLightbox\Events\DeletePressed;

#[OnNative(DeletePressed::class)]
public function handleDelete(?string $imageId = null): void
{
    // perform your delete logic here
}

Event payload summary

Event	Property	Type	Description
`ClosePressed`	`imageId`	`string\|null`	The `imageId` passed to `::show()`
`EditPressed`	`imageId`	`string\|null`	The `imageId` passed to `::show()`
`MarkupPressed`	`imageId`	`string\|null`	The `imageId` passed to `::show()`
`DeletePressed`	`imageId`	`string\|null`	The `imageId` passed to `::show()`

JavaScript (Vue / React / Inertia)

import { ImageLightbox, Events } from '@pteal79/plugin-image-lightbox';
import { on, off } from '@nativephp/native';

// Show the lightbox
await ImageLightbox.show({
    url:     'https://example.com/photo.jpg',
    imageId: 'abc-123',
    edit:    true,
    delete:  true,
    share:   true,
});

// Listen for events using the exported constants (avoids typos)
const onDelete = ({ imageId }) => console.log('Delete pressed for', imageId);
on(Events.DeletePressed, onDelete);

const onClose = ({ imageId }) => console.log('Closed for', imageId);
on(Events.ClosePressed, onClose);

// Clean up
off(Events.DeletePressed, onDelete);
off(Events.ClosePressed, onClose);

Available event constants:

Events.EditPressed   // 'Pteal79\\ImageLightbox\\Events\\EditPressed'
Events.MarkupPressed // 'Pteal79\\ImageLightbox\\Events\\MarkupPressed'
Events.DeletePressed // 'Pteal79\\ImageLightbox\\Events\\DeletePressed'
Events.ClosePressed  // 'Pteal79\\ImageLightbox\\Events\\ClosePressed'

Toolbar

The toolbar sits at the top of the screen. Each button is a white SF Symbol (iOS) or text label (Android) on a semi-transparent dark background for legibility over any image. The close button is always present on the right; action buttons appear on the left in the order: Edit → Markup → Share → Delete.

Share behaviour

Local file — shared directly via the native share sheet.
Remote URL — the image is downloaded to a temporary cache file first, then shared. If the image was already loaded for display, the cached copy is reused (no second download).
Share failures (network error, missing file) surface a toast / alert — the lightbox remains open.

Remote URL authentication

When loading a remote URL the plugin injects the current WebView session cookies into the URLSession / HttpURLConnection request automatically, so images served behind a Laravel session-authenticated route will load correctly.

Limitations

HEIC decoding on Android requires API 28+. On older devices the image may fail to render; a graceful error message is shown.
The plugin presents over the current top-most view controller / activity. Ensure no other full-screen modal is already covering the app when calling ::show().
The Edit, Markup, and Delete buttons are UI affordances only — the plugin dispatches an event and dismisses. Your application is responsible for the resulting action.
Very large images (>20 MP) may be slow to decode on low-end Android devices. Consider resizing on the server before passing to the lightbox.
The Share feature on Android requires the host app to have a FileProvider registered with the authority ${applicationId}.provider. NativePHP Mobile configures this by default, but if you see a FileUriExposedException you may need to add/adjust the provider in your app's AndroidManifest.xml.

License

MIT

pteal79 / plugin-image-lightbox

Maintainers

Package info

Statistics

Security