README

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

Blurred Image

An elegant wrapper around Blurhash for the TALL stack, so Laravel projects can show colorful blurred placeholders while the real image loads.

How it works

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.
Pass both the final image URL (or the associated Media Library model+collection) and the thumbnail URL to the Blade component called blurred-image.
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.

2025-12-14.19-16-48.mp4

Installation

Install the package with Composer:

composer require goodm4ven/blurred-image

If you use Spatie's Laravel Media Library 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"

Warning

Note that AlpineJS and its Intersect plugin 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 for more settings.

Views (if you need to override the Blade template):

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

Notes

Static assets: Generate a *-blurred-thumbnail.* file next to your source image with php artisan blurred-image:generate <imagePath> so the blurhash can render client-side.
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

Load both AlpineJS and its Intersect plugin before using the component.

Generate a blurred thumbnail before the first render:

php artisan blurred-image:generate storage/app/public/example.jpg

use GoodMaven\BlurredImage\Facades\BlurredImage;

BlurredImage::generate(storage_path('app/public/example.jpg'));

Use cases overview

Use the blurred-image component in two primary ways:

Static assets: Pass explicit image and thumbnail URLs for banners, seeded data, etc.
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

<x-goodmaven::blurred-image
    :imagePath="asset('images/hero.jpg')"
    :thumbnailImagePath="asset('images/hero-blurred-thumbnail.jpg')"
    :isDisplayEnforced="true"
    alt="Coastal trail"
/>

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');

<x-goodmaven::blurred-image
    :model="$user"
    :collection="'profile-picture'"
    :mediaIndex="0"
/>

Extra: Slot overlays and intersection tweaks

<x-goodmaven::blurred-image
    :image-path="asset('images/poster.jpg')"
    :thumbnail-image-path="asset('images/poster-blurred-thumbnail.jpg')"
    :is-eager-loaded="false"
    :is-display-enforced="false"
    width-class="w-full"
    height-class="h-[520px]"
>
    <div class="absolute inset-0 bg-gradient-to-t from-black/60"></div>
    <div class="relative z-10 p-6 text-white">
        <p class="text-lg font-semibold">Deferred reveal</p>
        <p class="text-sm text-white/70">Blurhash shows immediately; the full image waits for an intersection.</p>
    </div>
</x-goodmaven::blurred-image>

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

Development

Read this to understand MCP usage.
This package uses Workbench to simulate a Laravel environment.
- Run ./vendor/bin/testbench to use the artisan alternative commands.
- Composer scripts listed in composer.json wrap those commands.
- After running composer serve, visit http://localhost:8000 to see the demo page.

Testing

composer test

Note

For code coverage add --coverage, and for faster runs add --parallel.

Credits

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

goodm4ven / blurred-image

Maintainers

Details