Laravel Og Image Laravel Package

title: Customizing screenshots weight: 3

You can customize how OG images are generated by calling methods on the OgImage facade in your AppServiceProvider. All methods are chainable.

Size

By default, images are generated at 1200×630 pixels with a device scale factor of 2, resulting in crisp 2400×1260 pixel images. You can change the global default:

use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::size(1200, 630);
}

You can also override the size per component:

<x-og-image :width="800" :height="400">
    <div>This OG image will be 800×400</div>
</x-og-image>

Per-component dimensions take priority over the global config. When custom dimensions are used, the content hash includes the dimensions, so the same HTML at different sizes produces different images.

Format

The default format is JPEG. You can change it to PNG or WebP:

OgImage::format('webp');

Quality

You can set the image quality for JPEG and WebP formats in your config:

// config/og-image.php
'quality' => 80,

When set to null (the default), the screenshot driver's default quality is used. You can also set quality via configureScreenshot() for more control.

Disk

By default, images are stored on the public disk in the og-images directory. You can change both:

OgImage::disk('s3', 'og-images');

Chaining

All methods can be chained:

OgImage::format('webp')
    ->size(1200, 630)
    ->disk('s3', 'og-images');

Cloudflare

Instead of using Browsershot (the default), you can use Cloudflare's Browser Rendering to generate screenshots:

OgImage::useCloudflare(
    apiToken: env('CLOUDFLARE_API_TOKEN'),
    accountId: env('CLOUDFLARE_ACCOUNT_ID'),
);

For more details, see installation & setup.

Configuring the screenshot builder

For full control over the screenshot process, use configureScreenshot(). The closure receives the ScreenshotBuilder instance after the URL, size, disk, and driver have been set:

use Spatie\LaravelScreenshot\Enums\WaitUntil;
use Spatie\LaravelScreenshot\ScreenshotBuilder;

OgImage::configureScreenshot(function (ScreenshotBuilder $screenshot) {
    $screenshot->waitUntil(WaitUntil::NetworkIdle0);
});

This can be combined with useCloudflare() or useDriver(). The driver is applied first, then your configureScreenshot callback runs on top:

OgImage::useCloudflare(
        apiToken: env('CLOUDFLARE_API_TOKEN'),
        accountId: env('CLOUDFLARE_ACCOUNT_ID'),
    )
    ->configureScreenshot(function (ScreenshotBuilder $screenshot) {
        $screenshot->waitUntil(WaitUntil::NetworkIdle0);
    });

Common options

deviceScaleFactor

Controls the device pixel ratio. Defaults to 2, producing retina-quality 2400×1260 pixel images at the default 1200×630 viewport. Set to 1 if you prefer smaller file sizes over sharpness.

waitUntil

Determines when the page is considered loaded. Supported values:

• 'load': wait for the load event
• 'domcontentloaded': wait for the DOMContentLoaded event
• 'networkidle0': wait until there are no more than 0 network connections for at least 500ms
• 'networkidle2': wait until there are no more than 2 network connections for at least 500ms

waitForTimeout

Additional time to wait (in milliseconds) after the page has loaded. Useful if you need to wait for fonts or animations to complete.