Customizing screenshots | laravel-screenshot | Spatie

 SPATIE

  Laravel Screenshot
=====================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-screenshot](https://spatie.be/docs/laravel-screenshot/v1)  Basic-usage  Customizing screenshots

 Version   v1

 Other versions for crawler [v1](https://spatie.be/docs/laravel-screenshot/v1)

- [ Introduction ](https://spatie.be/docs/laravel-screenshot/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-screenshot/v1/support-us)
- [ Requirements ](https://spatie.be/docs/laravel-screenshot/v1/requirements)
- [ Installation & setup ](https://spatie.be/docs/laravel-screenshot/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-screenshot/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-screenshot/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-screenshot/v1/about-us)

Basic usage
-----------

- [ Taking screenshots ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/taking-screenshots)
- [ Customizing screenshots ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/customizing-screenshots)
- [ Saving screenshots to disks ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/saving-screenshots-to-disks)
- [ Queued screenshot generation ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/queued-screenshot-generation)
- [ Testing screenshots ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/testing-screenshots)

Drivers
-------

- [ Configuration ](https://spatie.be/docs/laravel-screenshot/v1/drivers/configuration)
- [ Customizing Browsershot ](https://spatie.be/docs/laravel-screenshot/v1/drivers/customizing-browsershot)
- [ Using the Cloudflare driver ](https://spatie.be/docs/laravel-screenshot/v1/drivers/using-the-cloudflare-driver)
- [ Custom drivers ](https://spatie.be/docs/laravel-screenshot/v1/drivers/custom-drivers)

Advanced usage
--------------

- [ Extending with macros ](https://spatie.be/docs/laravel-screenshot/v1/advanced-usage/extending-with-macros)

 Customizing screenshots
=======================

###  On this page

1. [ Viewport size ](#content-viewport-size)
2. [ Image format ](#content-image-format)
3. [ Image quality ](#content-image-quality)
4. [ Device scale factor ](#content-device-scale-factor)
5. [ Full page screenshots ](#content-full-page-screenshots)
6. [ Element screenshots ](#content-element-screenshots)
7. [ Clip region ](#content-clip-region)
8. [ Transparent background ](#content-transparent-background)
9. [ Wait strategies ](#content-wait-strategies)
10. [ Conditional customization ](#content-conditional-customization)
11. [ Debugging ](#content-debugging)

There are various options to customize the output of your screenshots.

Viewport size
-----------------------------------------------------------------------------------------------

By default, screenshots use a 1280x800 viewport. You can change this using `width()`, `height()`, or `size()`:

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->width(1920)
    ->height(1080)
    ->save('screenshot.png');

// Or use size() as a shorthand:
Screenshot::url('https://example.com')
    ->size(1920, 1080)
    ->save('screenshot.png');
```

Image format
--------------------------------------------------------------------------------------------

The image format is automatically determined from the file extension passed to `save()`. Supported formats:

- `.png` — PNG format (default for unknown extensions)
- `.jpg` / `.jpeg` — JPEG format
- `.webp` — WebP format

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')->save('screenshot.jpg'); // saves as JPEG
Screenshot::url('https://example.com')->save('screenshot.webp'); // saves as WebP
Screenshot::url('https://example.com')->save('screenshot.png'); // saves as PNG
```

Image quality
-----------------------------------------------------------------------------------------------

For JPEG and WebP formats, you can set the quality (0-100):

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->quality(80)
    ->save('screenshot.jpg');
```

Device scale factor
-----------------------------------------------------------------------------------------------------------------

By default, screenshots use a 2x device scale factor (retina). You can change this:

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

// Standard resolution
Screenshot::url('https://example.com')
    ->deviceScaleFactor(1)
    ->save('screenshot.png');

// 3x resolution
Screenshot::url('https://example.com')
    ->deviceScaleFactor(3)
    ->save('screenshot@3x.png');
```

Full page screenshots
-----------------------------------------------------------------------------------------------------------------------

By default, only the viewport is captured. To capture the entire scrollable page:

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->fullPage()
    ->save('full-page.png');
```

Element screenshots
-----------------------------------------------------------------------------------------------------------------

You can screenshot a specific element on the page using a CSS selector:

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->selector('.hero-section')
    ->save('hero.png');
```

Clip region
-----------------------------------------------------------------------------------------

You can capture a specific region of the page by specifying x, y coordinates and dimensions:

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->clip(0, 0, 800, 600)
    ->save('clipped.png');
```

Transparent background
--------------------------------------------------------------------------------------------------------------------------

To capture the page with a transparent background (useful for PNG screenshots of elements):

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->selector('.logo')
    ->omitBackground()
    ->save('logo.png');
```

Wait strategies
-----------------------------------------------------------------------------------------------------

By default, screenshots wait for the network to be idle (`networkidle2`). You can customize this behavior:

### Wait for a specific network state

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->waitUntil('networkidle0')
    ->save('screenshot.png');
```

### Wait for a CSS selector to appear

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->waitForSelector('.content-loaded')
    ->save('screenshot.png');
```

### Wait for a specific duration

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->waitForTimeout(3000) // wait 3 seconds
    ->save('screenshot.png');
```

Conditional customization
-----------------------------------------------------------------------------------------------------------------------------------

You can conditionally apply options using the `when` and `unless` methods:

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->when($needsFullPage, fn ($screenshot) => $screenshot->fullPage())
    ->when($isRetina, fn ($screenshot) => $screenshot->deviceScaleFactor(2))
    ->save('screenshot.png');
```

Debugging
-----------------------------------------------------------------------------------

You can call `dump` or `dd` on the builder to inspect its current state:

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->width(1920)
    ->fullPage()
    ->dump() // dumps the builder state and continues
    ->save('screenshot.png');
```