Customizing screenshots

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.