PHPackages                             goodm4ven/blurred-image - 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. goodm4ven/blurred-image

ActiveLibrary[Image & Media](/categories/media)

goodm4ven/blurred-image
=======================

An elegant wrapper around Blurhash for the TALL stack

v1.3.2(2mo ago)2420↓50%[9 PRs](https://github.com/GoodM4ven/PACKAGE_LARAVEL_blurred-image/pulls)MITPHPPHP ^8.4||^8.3CI passing

Since Dec 23Pushed 1mo agoCompare

[ Source](https://github.com/GoodM4ven/PACKAGE_LARAVEL_blurred-image)[ Packagist](https://packagist.org/packages/goodm4ven/blurred-image)[ Docs](https://github.com/goodm4ven/PACKAGE_LARAVEL_blurred-image)[ Fund](https://www.buymeacoffee.com/GoodM4ven)[ GitHub Sponsors](https://github.com/GoodM4ven)[ RSS](/packages/goodm4ven-blurred-image/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (20)Versions (27)Used By (0)

بسم الله الرحمن الرحيم

blurred-image
=============

[](#blurred-image)

[![Latest Version on Packagist](https://camo.githubusercontent.com/0fe640da69d822805da7ff3b21fddc600dddb60bdf24763fb48f648499a1ca52/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f676f6f646d3476656e2f626c75727265642d696d6167652e7376673f7374796c653d666f722d7468652d626164676526636f6c6f723d67726179)](https://packagist.org/packages/goodm4ven/blurred-image)[![GitHub Tests Action Status](https://camo.githubusercontent.com/d82ce178c602e268f91f50633c661569c1dd6a41f96ed876d30ef4383dea4b6a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f676f6f646d3476656e2f5041434b4147455f4c41524156454c5f626c75727265642d696d6167652f706573742e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666f722d7468652d626164676526636f6c6f723d666f72657374677265656e)](https://github.com/goodm4ven/PACKAGE_LARAVEL_blurred-image/actions?query=workflow%3Apest+branch%3Amain)[![Coverage Status](https://camo.githubusercontent.com/1128867914ff6b4a2bc18649779ed1401317b96730f9d3c301c3dd67536263f8/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f676f6f646d3476656e2f5041434b4147455f4c41524156454c5f626c75727265642d696d6167652f6d61696e3f7374796c653d666f722d7468652d626164676526636f6c6f723d707572706c65)](https://codecov.io/gh/goodm4ven/PACKAGE_LARAVEL_blurred-image)[![Total Downloads](https://camo.githubusercontent.com/df796de00b3ea6d7300314daede7200899b20793ea719f7409eabb2d2fba53ae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f676f6f646d3476656e2f626c75727265642d696d6167652e7376673f7374796c653d666f722d7468652d626164676526636f6c6f723d626c7565)](https://packagist.org/packages/goodm4ven/blurred-image)

An elegant wrapper around [Blurhash](https://blurha.sh) for the [TALL stack](https://tallstack.dev), so Laravel projects can show colorful blurred placeholders while the real image loads.

[![](./.github/images/banner.png)](./.github/images/banner.png)    2025-12-14.19-16-48.mp4    How it works
------------

[](#how-it-works)

1. Generate a tiny blurred thumbnail for the image you want to render. You can do that via the Artisan command, the `BlurredImage` facade, or by registering a conversion through Spatie Media Library.
2. Pass both the final image URL (or the associated Media Library model+collection) and the thumbnail URL to the [Blade component](https://laravel.com/docs/blade) called `blurred-image`.
3. The component:
    - Renders an empty gray canvas immediately.
    - Sends the thumbnail through Blurhash to animate a colorful, blurred version of the image.
    - Replaces the blurhash with the real image once it has fully intersected the viewport or finished downloading, depending on your configuration.

Once configured, the component handles the placeholder animation for you so you can focus on content.

Installation
------------

[](#installation)

Install the package with [`Composer`](https://getcomposer.org/):

```
composer require goodm4ven/blurred-image
```

If you use [Spatie's Laravel Media Library](https://spatie.be/docs/laravel-medialibrary/) and want the `model`/`collection` scenario, install that package and add the `HasBlurredImages` trait to your model so `addBlurredThumbnailConversion` conversion method becomes available:

```
composer require spatie/laravel-medialibrary
```

```
use GoodMaven\BlurredImage\Concerns\HasBlurredImages;
use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class User extends Model implements HasMedia
{
    use InteractsWithMedia;
    use HasBlurredImages;

    public function registerMediaCollections(): void
    {
        $this
            ->addMediaCollection('profile-picture')
            ->singleFile()
            ->registerMediaConversions(function (Media $media) {
                $this->addBlurredThumbnailConversion();
            });
    }
}
```

Publish the assets so the JavaScript helper, CSS, and placeholder images are copied to `public/vendor/blurred-image`.

```
php artisan vendor:publish --tag="blurred-image-assets"
```

Note

You should add the **enforced** asset publishing process to your app composer's workflow:

```
{
    ...
    "scripts": {
        ...
        "post-autoload-dump": [
            ...
            "@php artisan vendor:publish --tag=blurred-image-assets --force --ansi"

```

Warning

Note that [AlpineJS](https://alpinejs.dev) and its [Intersect plugin](https://alpinejs.dev/plugins/intersect) are not bundled with these assets.

You may also publish additional resources to tailor the package to your project: - Config file (to adjust defaults such as `conversion_name` and the component flags):

    ```
    php artisan vendor:publish --tag="blurred-image-config"
    ```

    - Check the current [configurations](config/blurred-image.php) for more settings.
- Views (if you need to override the Blade template):

    ```
    php artisan vendor:publish --tag="blurred-image-views"
    ```

### Notes

[](#notes)

- **Static assets**: Generate a `*-blur-thumbnail.*` file next to your source image with `php artisan blurred-image:generate ` so the blurhash can render client-side.
- **Optimization**: `is_generation_optimized` is enabled by default and runs `blurred-image:optimize` on both the source image and the generated thumbnail whenever you call the generator command. The optimize command converts supported inputs to `.webp` first, then optimizes the resulting WebP image.
- **Media Library collections**: Always sync `conversion_name` with the config by using `addBlurredThumbnailConversion` from the `HasBlurredImages` trait.
- **Intersection/delay**: Set `is_eager_loaded` to preload the image or leave it `false` to wait for intersection; adjust `is_display_enforced` if the final image should appear before an intersection callback.

Usage
-----

[](#usage)

- **Load both [AlpineJS](https://alpinejs.dev) and its [Intersect plugin](https://alpinejs.dev/plugins/intersect) before using the component.**
- Generate a blurred thumbnail before the first render:

    ```
    php artisan blurred-image:generate storage/app/public/example.jpg
    // or for an entire directory, in a nested manner!
    php artisan blurred-image:generate storage/app/public/images --directory
    ```

    ```
    use GoodMaven\BlurredImage\Facades\BlurredImage;

    BlurredImage::generate(storage_path('app/public/example.jpg'));
    // Or for the inner directories as well...
    BlurredImage::generate(storage_path('app/public/images'));
    ```

### Use cases overview

[](#use-cases-overview)

Use the `blurred-image` component in two primary ways:

1. **Static assets**: Pass explicit image and thumbnail URLs for banners, seeded data, etc.
2. **Media Library**: Provide a model and collection, letting the component read the conversion registered via `HasBlurredImages`. Use `mediaIndex` to select from multiple media items.

Extra options to consider:

- **Slot overlays**: Place foreground content inside the component slot so your UI sits atop the blurhash and final image.
- **Intersection tuning**: Toggle `is_eager_loaded` to preload the image, toggle `is_display_enforced` to reveal the final image before intersection fires.

### 1. Render with explicit paths

[](#1-render-with-explicit-paths)

```

```

### 2. Render from the Media Library

[](#2-render-from-the-media-library)

Attach media to a model that uses `HasBlurredImages` and its conversion method:

```
$user = User::first();

$user
    ->addMedia($pathToImage)
    ->preservingOriginal()
    ->toMediaCollection('profile-picture');
```

```

```

### Extra: Slot overlays and intersection tweaks

[](#extra-slot-overlays-and-intersection-tweaks)

```

        Deferred reveal
        Blurhash shows immediately; the full image waits for an intersection.

```

Configuration for flags such as `is_eager_loaded`, `is_display_enforced`, and the `conversion_name` lives in the configuration file.

### Edge Case

[](#edge-case)

Important

If the parent element, that contains the component, **doesn’t have an explicit `height`**, like being `absolute` or whatever, **you MUST explicitely set the `heightClass` yourself**; like providing `aspect-[4/3]` or `h-48` classes. And ensure a proper `width` too. You can check the props defaults at the top of [blurred-image.blade.php](./resources/views/components/blurred-image.blade.php) file.

Development
-----------

[](#development)

This package was initiated based on my [Laravel package template](https://github.com/goodm4ven/TEMPLATE_PACKAGE_TALL/blob/main/README.md#development) that is built on top of [Spatie's](https://github.com/spatie/package-skeleton-laravel). Make sure to read the docs for both.

### Tasks

[](#tasks)

- // TODO Extract the validated image file types to a configurable setting
- // TODO Rework the demo Livewire component setup to load more images into the page, from both DB and fake-urls, and visualize the benifit

Support
-------

[](#support)

Support ongoing package maintenance as well as the development of **other projects** through [sponsorship](https://github.com/sponsors/GoodM4ven) or one-time [donations](https://github.com/sponsors/GoodM4ven?frequency=one-time&sponsor=GoodM4ven) if you prefer.

### Credits

[](#credits)

- Inspired by [Blurhash](https://github.com/woltapp/blurhash).
- [TALL Stack Community](https://tallstack.dev)
- [TailwindCSS](https://tailwindcss.com)
- [AlpineJS](https://alpinejs.dev)
- [Laravel](https://laravel.com)
- [Laravel Media Library](https://github.com/spatie/laravel-medialibrary)
- [Spatie Team](https://github.com/Spatie)
- [ChatGPT & Codex](https://developers.openai.com/codex)
- [GoodM4ven](https://github.com/GoodM4ven)
- [All Contributors](../../contributors)

والحمد لله رب العالمين

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance87

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 98.2% 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 ~3 days

Recently: every ~11 days

Total

18

Last Release

86d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2fe03bedf65c411e3623e9c103eb2dc4626c5d4ee3fab62cfb98d88caab82a4b?d=identicon)[GoodM4ven](/maintainers/GoodM4ven)

---

Top Contributors

[![GoodM4ven](https://avatars.githubusercontent.com/u/121377476?v=4)](https://github.com/GoodM4ven "GoodM4ven (56 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

alpinejsblurhashimagelaravelloadingplaceholdertallstacklaravelimageloadingplaceholderBlurtallstackblurhashGoodM4venblurred-image

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/goodm4ven-blurred-image/health.svg)

```
[![Health](https://phpackages.com/badges/goodm4ven-blurred-image/health.svg)](https://phpackages.com/packages/goodm4ven-blurred-image)
```

###  Alternatives

[intervention/image-laravel

Laravel Integration of Intervention Image

1536.5M102](/packages/intervention-image-laravel)[bkwld/croppa

Image thumbnail creation through specially formatted URLs for Laravel

510496.0k23](/packages/bkwld-croppa)[ralphjsmit/laravel-glide

Auto-magically generate responsive images from static image files.

4719.6k5](/packages/ralphjsmit-laravel-glide)[joshembling/image-optimizer

Optimize your Filament images before they reach your database.

111145.4k12](/packages/joshembling-image-optimizer)[saasykit/laravel-open-graphy

An awesome open graph image (social cards) generator package for Laravel.

13057.0k](/packages/saasykit-laravel-open-graphy)[spatie/laravel-og-image

Generate OG images for your Laravel app

305.2k](/packages/spatie-laravel-og-image)

PHPackages © 2026

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