Customizing Browsershot | laravel-pdf | Spatie

 SPATIE

  Laravel PDF
==============

spatie.be/open-source

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

 Version   v2   v1

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

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

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

- [ Creating PDFs ](https://spatie.be/docs/laravel-pdf/v2/basic-usage/creating-pdfs)
- [ Responding with PDFs ](https://spatie.be/docs/laravel-pdf/v2/basic-usage/responding-with-pdfs)
- [ Formatting PDFs ](https://spatie.be/docs/laravel-pdf/v2/basic-usage/formatting-pdfs)
- [ Saving PDFs to disks ](https://spatie.be/docs/laravel-pdf/v2/basic-usage/saving-pdfs-to-disks)
- [ Queued PDF generation ](https://spatie.be/docs/laravel-pdf/v2/basic-usage/queued-pdf-generation)
- [ Testing PDFs ](https://spatie.be/docs/laravel-pdf/v2/basic-usage/testing-pdfs)
- [ Setting defaults ](https://spatie.be/docs/laravel-pdf/v2/basic-usage/setting-defaults)

Drivers
-------

- [ Configuration ](https://spatie.be/docs/laravel-pdf/v2/drivers/configuration)
- [ Customizing Browsershot ](https://spatie.be/docs/laravel-pdf/v2/drivers/customizing-browsershot)
- [ Using the Cloudflare driver ](https://spatie.be/docs/laravel-pdf/v2/drivers/using-the-cloudflare-driver)
- [ Using the DOMPDF driver ](https://spatie.be/docs/laravel-pdf/v2/drivers/using-the-dompdf-driver)
- [ Generating PDFs on AWS Lambda ](https://spatie.be/docs/laravel-pdf/v2/drivers/generating-pdfs-on-aws-lambda)
- [ Using the Gotenberg driver ](https://spatie.be/docs/laravel-pdf/v2/drivers/using-the-gotenberg-driver)
- [ Using the WeasyPrint driver ](https://spatie.be/docs/laravel-pdf/v2/drivers/using-the-weasyprint-driver)
- [ Custom drivers ](https://spatie.be/docs/laravel-pdf/v2/drivers/custom-drivers)

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

- [ Creating PDFs with multiple pages ](https://spatie.be/docs/laravel-pdf/v2/advanced-usage/creating-pdfs-with-multiple-pages)
- [ Using Tailwind ](https://spatie.be/docs/laravel-pdf/v2/advanced-usage/using-tailwind)
- [ Extending with Macros ](https://spatie.be/docs/laravel-pdf/v2/advanced-usage/extending-with-macros)

 Customizing Browsershot
=======================

###  On this page

1. [ Configuration-Based Customization ](#content-configuration-based-customization)
2. [ Per-PDF Customization ](#content-per-pdf-customization)
3. [ Advanced Browsershot Configuration ](#content-advanced-browsershot-configuration)

When using the Browsershot driver, you can customize the underlying [Browsershot](https://spatie.be/docs/browsershot) instance. This is only applicable when using the `browsershot` driver.

Configuration-Based Customization
-----------------------------------------------------------------------------------------------------------------------------------------------------------

For settings that apply to all PDFs in your application, use the [configuration file](/docs/advanced-usage/configuration) to set defaults. This is especially useful for binary paths, Chrome arguments, and language settings.

Per-PDF Customization
-----------------------------------------------------------------------------------------------------------------------

You can customize the Browsershot instance for individual PDFs by calling the `withBrowsershot` method. This method accepts a closure that receives the Browsershot instance as its only argument.

Here's an example of how you can call Browsershot's `scale` method:

```
use Spatie\LaravelPdf\Facades\Pdf;
use Spatie\Browsershot\Browsershot;

Pdf::view('test')
    ->withBrowsershot(function (Browsershot $browsershot) {
        $browsershot->scale(0.5);
    })
    ->save($this->targetPath);
```

The `withBrowsershot()` closure runs after configuration defaults are applied, allowing you to override or extend the default settings on a per-PDF basis.

Advanced Browsershot Configuration
--------------------------------------------------------------------------------------------------------------------------------------------------------------

You can also use the `withBrowsershot` method to set options on the Browsershot instance. For example, you can disable web security and allow file access from files.

These flags are commonly needed when your PDF templates reference local assets (CSS, images, fonts) or when you need to bypass CORS restrictions during PDF generation. Without these flags, Chrome might block access to local resources, causing missing styles or images in your PDFs.

The two Chrome flags being set are:

- `--disable-web-security`: Disables Chrome's same-origin policy and other web security features
- `--allow-file-access-from-files`: Allows local files to access other local files (normally blocked for security)

You can set these as defaults for all PDFs:

```
// typically, in a service provider

Pdf::default()->withBrowsershot(function (Browsershot $browsershot) {
    $browsershot->setOption('args', [
        '--disable-web-security',
        '--allow-file-access-from-files',
    ]);
});
```