README

Generate OG images for your Laravel app

This package makes it easy to generate Open Graph images for your Laravel application. Define your OG image HTML inline in your Blade views, and the package automatically generates screenshot images using spatie/laravel-screenshot, serves them via a dedicated route, and caches them on disk.

Your OG image templates inherit your page's existing CSS, fonts, and Vite assets. No separate CSS configuration needed.

No external API needed. Everything runs on your own server.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Documentation

You'll find full documentation on our documentation site.

Basic usage

Use the Blade component to define your OG image inline:

<x-og-image>
    <div class="w-full h-full bg-blue-900 text-white flex items-center justify-center">
        <h1 class="text-6xl font-bold">{{ $post->title }}</h1>
    </div>
</x-og-image>

This outputs a hidden <template> tag and <meta> tags pointing to a generated screenshot of your HTML at 1200×630 pixels.

How it works

1. Your HTML is rendered inside a <template data-og-image> tag on the page
2. The page URL is cached, keyed by the md5 hash of the HTML content
3. Meta tags point to /og-image/{hash}.jpeg
4. When that URL is first requested, the page is visited with ?ogimage appended, rendering just the template content with the page's full CSS at 1200×630
5. The generated image is saved to your public disk and served directly with cache headers
6. Subsequent requests serve the image from disk (or CDN cache)

Preview any OG image by appending ?ogimage to the page URL.

Installation

You can install the package via composer:

composer require spatie/laravel-og-image

This package requires spatie/laravel-screenshot, which uses Browsershot under the hood. Make sure you have Node.js and a Chrome/Chromium binary installed.

You can optionally publish the config file:

php artisan vendor:publish --tag="og-image-config"

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Freek Van der Herten
• All Contributors

License

The MIT License (MIT). Please see License File for more information.