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/v1)  Advanced-usage  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/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-pdf/v1/support-us)
- [ Requirements ](https://spatie.be/docs/laravel-pdf/v1/requirements)
- [ Installation & setup ](https://spatie.be/docs/laravel-pdf/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-pdf/v1/questions-issues)
- [ Alternatives ](https://spatie.be/docs/laravel-pdf/v1/alternatives)
- [ Changelog ](https://spatie.be/docs/laravel-pdf/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-pdf/v1/about-us)

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

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

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

- [ Configuration ](https://spatie.be/docs/laravel-pdf/v1/advanced-usage/configuration)
- [ Creating PDFs with multiple pages ](https://spatie.be/docs/laravel-pdf/v1/advanced-usage/creating-pdfs-with-multiple-pages)
- [ Customizing Browsershot ](https://spatie.be/docs/laravel-pdf/v1/advanced-usage/customizing-browsershot)
- [ Generating PDFs on AWS Lambda ](https://spatie.be/docs/laravel-pdf/v1/advanced-usage/generating-pdfs-on-aws-lambda)
- [ Using Tailwind ](https://spatie.be/docs/laravel-pdf/v1/advanced-usage/using-tailwind)
- [ Extending with Macros ](https://spatie.be/docs/laravel-pdf/v1/advanced-usage/extending-with-macros)

      You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command:

 `                                    composer show spatie/laravel-pdf                                                                                                                                                                                                                                    `

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)

Under the hood, Laravel PDF uses [Browsershot](https://spatie.be/docs/browsershot) to generate the PDFs. While Laravel PDF provides a simple interface to generate PDFs, you can still use Browsershot directly to customize the PDFs.

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.

This global configuration means all PDFs generated in your app will use these Browsershot settings, rather than having to configure them individually for each PDF.

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)

```
use Spatie\LaravelPdf\PdfFactory;

class AppServiceProvider extends ServiceProvider
{
    //...
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        app()->bind(PdfFactory::class, function ($service, $app) {
            return (new PdfFactory())->withBrowsershot(
                function ($browserShot) {
                    $browserShot->setOption(
                        'args', [
                            '--disable-web-security',
                            '--allow-file-access-from-files',
                        ],
                    );
                }
            );
        });
    }
}
```