Customizing screenshots | laravel-og-image | Spatie SPATIE Laravel Open Graph Image =========================== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-og-image](https://spatie.be/docs/laravel-og-image/v1) Basic-usage Customizing screenshots Version v1 Other versions for crawler [v1](https://spatie.be/docs/laravel-og-image/v1) - [ Introduction ](https://spatie.be/docs/laravel-og-image/v1/introduction) - [ Requirements ](https://spatie.be/docs/laravel-og-image/v1/requirements) - [ Installation & setup ](https://spatie.be/docs/laravel-og-image/v1/installation-setup) - [ Support us ](https://spatie.be/docs/laravel-og-image/v1/support-us) - [ Questions and issues ](https://spatie.be/docs/laravel-og-image/v1/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-og-image/v1/changelog) - [ About us ](https://spatie.be/docs/laravel-og-image/v1/about-us) Basic usage ----------- - [ How it works ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/how-it-works) - [ Getting started ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/getting-started) - [ Customizing screenshots ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/customizing-screenshots) - [ Defining fallback images ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/defining-fallback-images) - [ Caching and storage ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/managing-caching-and-storage) - [ Pre-generating images ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/pre-generating-images) - [ Clearing generated images ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/clearing-generated-images) Advanced usage -------------- - [ Customizing the page URL ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/customizing-the-page-url) - [ Using a custom screenshot driver ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/using-a-custom-screenshot-driver) - [ Customizing the screenshot layout ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/customizing-the-screenshot-layout) - [ Customizing actions ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/customizing-actions) - [ Troubleshooting ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/troubleshooting) - [ Using a hosted solution ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/using-a-hosted-solution) - [ Using Laravel Boost ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/using-laravel-boost) Customizing screenshots ======================= ### On this page 1. [ Size ](#content-size) 2. [ Format ](#content-format) 3. [ Quality ](#content-quality) 4. [ Disk ](#content-disk) 5. [ Chaining ](#content-chaining) 6. [ Cloudflare ](#content-cloudflare) 7. [ Configuring the screenshot builder ](#content-configuring-the-screenshot-builder) 8. [ Common options ](#content-common-options) 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: ``` This OG image will be 800×400 ``` 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](/docs/laravel-og-image/v1/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.