Defining fallback images | 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  Defining fallback images

 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)

 Defining fallback images
========================

###  On this page

1. [ Registering a fallback ](#content-registering-a-fallback)
2. [ Skipping the fallback for specific pages ](#content-skipping-the-fallback-for-specific-pages)
3. [ How it works ](#content-how-it-works)

When a page doesn't use the `` component, no OG image meta tags are generated. You can register a fallback to automatically provide an OG image for these pages.

Registering a fallback
--------------------------------------------------------------------------------------------------------------------------

In your `AppServiceProvider`, register a closure that receives the current request and returns a view:

```
use Illuminate\Http\Request;
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::fallbackUsing(function (Request $request) {
        return view('og-image.fallback', [
            'title' => config('app.name'),
        ]);
    });
}
```

The closure receives the full `Request` object, so you can use route parameters, model bindings, or any other request data to customize the fallback:

```
OgImage::fallbackUsing(function (Request $request) {
    $title = $request->route('post')?->title ?? config('app.name');

    return view('og-image.fallback', [
        'title' => $title,
        'url' => $request->url(),
    ]);
});
```

The fallback view should be a regular Blade view with just the HTML content, no layout or scripts needed. Like ``, the screenshot inherits the page's ``, so your CSS, fonts, and Vite assets are available automatically.

```
{{-- resources/views/og-image/fallback.blade.php --}}

    {{ $title }}

```

Skipping the fallback for specific pages
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Return `null` from the closure to skip the fallback for a specific request:

```
OgImage::fallbackUsing(function (Request $request) {
    if ($request->routeIs('admin.*')) {
        return null;
    }

    return view('og-image.fallback', [
        'title' => config('app.name'),
    ]);
});
```

How it works
--------------------------------------------------------------------------------------------

When a page is rendered without an `` component and a fallback is registered, the middleware will:

1. Call your closure with the current request
2. Render the returned view
3. Inject the `` tag and `og:image` meta tags into the response

From that point on, the fallback image goes through the same screenshot and caching pipeline as any explicit ``. Pages that do have an `` component are never affected by the fallback.