PHPackages                             pteal79/plugin-image-lightbox - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. pteal79/plugin-image-lightbox

ActiveNativephp-plugin[Image & Media](/categories/media)

pteal79/plugin-image-lightbox
=============================

A NativePHP plugin that displays images in a full-screen native lightbox with zoom, pan, and share support.

1.0.9(2mo ago)157↓70%MITKotlinPHP ^8.2

Since Mar 26Pushed 2mo agoCompare

[ Source](https://github.com/pteal79/plugin-image-lightbox)[ Packagist](https://packagist.org/packages/pteal79/plugin-image-lightbox)[ RSS](/packages/pteal79-plugin-image-lightbox/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (10)Dependencies (4)Versions (11)Used By (0)

ImageLightbox Plugin for NativePHP Mobile
=========================================

[](#imagelightbox-plugin-for-nativephp-mobile)

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

[](#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)

[](#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
------------

[](#requirements)

### Android

[](#android)

RequirementDetailPermission`android.permission.INTERNET` (remote URLs) — added automatically via `nativephp.json`FileProviderThe 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 supportAndroid 9 (API 28)+ via `ImageDecoder`. Older devices fall back to `BitmapFactory`; HEIC may not decode on API < 28.### iOS

[](#ios)

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

---

Usage
-----

[](#usage)

### PHP — Livewire / Blade

[](#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

[](#parameters)

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

[](#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`

[](#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`

[](#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`

[](#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`

[](#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-payload-summary)

EventPropertyTypeDescription`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)
----------------------------------

[](#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
-------

[](#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
---------------

[](#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
-------------------------

[](#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
-----------

[](#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
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 89% of packages

Maintenance86

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

10

Last Release

73d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/167c450c5528b16682698e73dc0a8cb5b537244340d1696502cfc3f3f92ebdd1?d=identicon)[pteal79](/maintainers/pteal79)

---

Top Contributors

[![Elite-Cleaning](https://avatars.githubusercontent.com/u/102381701?v=4)](https://github.com/Elite-Cleaning "Elite-Cleaning (10 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/pteal79-plugin-image-lightbox/health.svg)

```
[![Health](https://phpackages.com/badges/pteal79-plugin-image-lightbox/health.svg)](https://phpackages.com/packages/pteal79-plugin-image-lightbox)
```

###  Alternatives

[goat1000/svggraph

Generates SVG graphs

133890.0k3](/packages/goat1000-svggraph)[gravatarphp/gravatar

Gravatar URL builder which is most commonly called as a Gravatar library

12644.1k2](/packages/gravatarphp-gravatar)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)