Customizing Browsershot | laravel-screenshot | Spatie

 SPATIE

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

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-screenshot](https://spatie.be/docs/laravel-screenshot/v1)  Drivers  Customizing Browsershot

 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 Browsershot
=======================

###  On this page

1. [ Global configuration ](#content-global-configuration)
2. [ Per-screenshot customization ](#content-per-screenshot-customization)
3. [ Running in no-sandbox mode ](#content-running-in-no-sandbox-mode)
4. [ Limitations ](#content-limitations)

The Browsershot driver uses [spatie/browsershot](https://spatie.be/docs/browsershot) under the hood. You can customize its behavior globally via the config file or per-screenshot using the `withBrowsershot()` method.

Global configuration
--------------------------------------------------------------------------------------------------------------------

The config file lets you set binary paths and other Browsershot defaults:

```
// config/laravel-screenshot.php

'browsershot' => [
    'node_binary' => env('LARAVEL_SCREENSHOT_NODE_BINARY'),
    'npm_binary' => env('LARAVEL_SCREENSHOT_NPM_BINARY'),
    'chrome_path' => env('LARAVEL_SCREENSHOT_CHROME_PATH'),
    'node_modules_path' => env('LARAVEL_SCREENSHOT_NODE_MODULES_PATH'),
    'bin_path' => env('LARAVEL_SCREENSHOT_BIN_PATH'),
    'temp_path' => env('LARAVEL_SCREENSHOT_TEMP_PATH'),
    'no_sandbox' => env('LARAVEL_SCREENSHOT_NO_SANDBOX', false),
],
```

Per-screenshot customization
--------------------------------------------------------------------------------------------------------------------------------------------

For one-off customizations, use the `withBrowsershot()` method. This gives you direct access to the underlying Browsershot instance:

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

Screenshot::url('https://example.com')
    ->withBrowsershot(function (Browsershot $browsershot) {
        $browsershot
            ->setExtraHttpHeaders(['Authorization' => 'Bearer token'])
            ->userAgent('My Custom User Agent');
    })
    ->save('screenshot.png');
```

You can use any method available on the [Browsershot](https://spatie.be/docs/browsershot) instance:

```
Screenshot::url('https://example.com')
    ->withBrowsershot(function (Browsershot $browsershot) {
        $browsershot
            ->setExtraHttpHeaders(['Cookie' => 'session=abc123'])
            ->dismissDialogs()
            ->timeout(60);
    })
    ->save('screenshot.png');
```

Running in no-sandbox mode
--------------------------------------------------------------------------------------------------------------------------------------

If you're running in a Docker container or other restricted environment, you may need to run Chrome without sandboxing:

```
LARAVEL_SCREENSHOT_NO_SANDBOX=true
```

Or per-screenshot:

```
Screenshot::url('https://example.com')
    ->withBrowsershot(fn (Browsershot $browsershot) => $browsershot->noSandbox())
    ->save('screenshot.png');
```

Limitations
-----------------------------------------------------------------------------------------

The `withBrowsershot()` method cannot be used together with `saveQueued()`. Closures cannot be serialized for the queue. An exception will be thrown if you try.