Laravel Head

Introduction

laravel/head is the official Laravel package for managing your application’s document <head> through a fluent API. It supports title and meta tags, Open Graph, canonical URLs, robots directives, performance hints, and structured data, and works with Blade, Livewire, and Inertia. v0.1.0 was released on July 28, 2026.

composer require laravel/head

Resolution priority

The head data for a page is resolved through the following five layers, from lowest to highest priority.

Page defaults
Route group metadata
Route metadata
Runtime metadata
Error page metadata

Higher layers overwrite lower ones on a per-field basis. For example, a runtime title replaces a route title, but not its description.

Registering defaults

use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;
use Laravel\Head\Enums\OgType;

Head::defaults(function (HeadBuilder $head) {
    $head
        ->title('Acme', suffix: ' - Acme')
        ->description('Build something great.')
        ->canonical()
        ->og(siteName: 'Acme', type: OgType::Website)
        ->searchableByRobots()
        ->preconnect('https://fonts.example.com');
});

The defaults layer is the lowest-priority page layer. Unless a higher layer sets a title, Acme is used verbatim; when a higher layer sets a title, the inherited suffix is applied (Head::title('About') becomes About - Acme).

Route metadata

Static pages can attach metadata directly to their route definitions.

Route::view('/contact', 'contact')
    ->name('contact')
    ->withHead(
        title: 'Contact Us',
        description: 'Get in touch.',
    );

You can also apply metadata common to a whole group.

Route::withHead(robots: 'noindex, nofollow')
    ->prefix('admin')
    ->name('admin.')
    ->group(function () {
        Route::get('/dashboard', DashboardController::class)
            ->name('dashboard')
            ->withHead(title: 'Dashboard');
    });

withHead() stores plain arrays through Laravel’s standard route metadata API (under the head key of ->metadata()), so it remains compatible with cached routes.

Runtime metadata

Values that aren’t known until the request arrives — like a post title — are set at runtime via the Head facade.

use App\Models\Post;
use Laravel\Head\Facades\Head;

public function show(Post $post)
{
    Head::title($post->title)
        ->description($post->description);

    return view('posts.show', ['post' => $post]);
}

Conditional metadata is expressed fluently with when() / unless().

Head::title($post->title)
    ->when($post->isDraft(), fn ($head) => $head->hiddenFromRobots());

Error pages

You can also register metadata for each status code.

use Laravel\Head\ErrorPages;
use Laravel\Head\Facades\Head;

Head::errors(function (ErrorPages $errors) {
    $errors->defaults(robots: 'noindex, follow');

    $errors->status(404,
        title: 'Page Not Found',
        description: 'The page you are looking for could not be found.',
    );
});

When a registered error status is rendered, this metadata takes precedence over every other layer.

Open Graph and Twitter Card

Set Open Graph properties with og() and add images, videos, or audio with methods like ogImage().

use Laravel\Head\Enums\ImageType;
use Laravel\Head\Enums\OgType;

Head::og(type: OgType::Article, title: $post->title)
    ->ogImage($post->hero_image_url)
    ->ogImage(
        $post->gallery_image_url,
        alt: $post->gallery_image_alt,
        width: 1200,
        height: 630,
        type: ImageType::Jpeg,
    );

The document title and description automatically fill in an unset og:title and og:description. Twitter Card renders automatically from the same title, description, and image as Open Graph as long as you register it in your defaults.

use Laravel\Head\Enums\TwitterCard;
use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;

Head::defaults(fn (HeadBuilder $head) => $head->twitter(
    card: TwitterCard::SummaryWithLargeImage,
));

You can also explicitly override the Twitter values on individual pages.

Head::twitter(title: $post->social_title)
    ->twitterImage($post->social_image_url, alt: $post->title);

PWA, performance, and icons

The pwa() helper sets the <head> tags you need for an installable web app in one call.

Head::pwa(
    name: 'Acme',
    manifest: '/site.webmanifest',
    themeColor: '#0f172a',
    appleTouchIcon: '/apple-touch-icon.png',
    appleWebAppStatusBarStyle: 'black',
);

Theme color

Theme color can be set globally, per route, or at runtime. Use the Media enum to specify per-media theme colors.

use Laravel\Head\Enums\Media;

Head::themeColor('#ffffff', media: Media::Light)
    ->themeColor('#111827', media: Media::Dark);

Media also includes Portrait and Landscape.

App metadata and icons

Laravel Head includes helpers for common browser and app metadata.

use Laravel\Head\Enums\ImageType;
use Laravel\Head\Enums\Media;

Head::applicationName('Acme')
    ->colorScheme('light dark')
    ->referrer('strict-origin-when-cross-origin')
    ->viewport('width=device-width, initial-scale=1')
    ->appleWebAppTitle('Acme')
    ->webAppCapable()
    ->appleWebAppStatusBarStyle('black')
    ->favicon('/favicon.svg', type: ImageType::Svg)
    ->icon('/favicon-32x32.png', type: ImageType::Png, sizes: '32x32')
    ->appleTouchIcon('/apple-touch-icon.png', sizes: '180x180')
    ->appleTouchStartupImage('/launch.png', media: Media::Portrait)
    ->maskIcon('/safari-pinned-tab.svg', color: '#111827')
    ->manifest('/site.webmanifest');

favicon() is an alias for icon() and accepts the same type, sizes, and media arguments.

Performance and discoverability

Laravel Head can also render performance hints, pagination links, locale alternates, and feed discovery tags.

Head::preload(asset('fonts/inter.woff2'), as: 'font', crossorigin: true)
    ->prefetch(asset('images/next.webp'))
    ->preconnect('https://cdn.example.com')
    ->dnsPrefetch('https://analytics.example.com')
    ->paginate($posts)
    ->alternates([
        'en' => 'https://example.com/en/about',
        'fr' => 'https://example.com/fr/about',
        'x-default' => 'https://example.com/about',
    ])
    ->feed('/feed', title: 'Acme RSS')
    ->feed('/feed.atom', type: 'atom', title: 'Acme Atom');

preloadAsset() / prefetchAsset() resolve the URL with the asset() helper and detect the as attribute from the extension.

Head::preloadAsset('fonts/inter.woff2')
    ->prefetchAsset('images/next.webp');

<link rel="preload" href="https://example.com/fonts/inter.woff2" as="font" crossorigin>
<link rel="prefetch" href="https://example.com/images/next.webp" as="image">

Custom tags

Tags without a dedicated method can be added with meta() / link().

Head::meta('format-detection', 'telephone=no')
    ->meta('article:author', $post->author->name)
    ->link('search', '/opensearch.xml', [
        'type' => 'application/opensearchdescription+xml',
        'title' => 'Acme Search',
    ]);

meta() uses name= for ordinary meta tags, but automatically switches for keys that should use property=, such as Open Graph (og:) or article metadata (article:).

Head::meta('description', 'About Acme')
    ->meta('og:title', 'About Acme');

<meta name="description" content="About Acme">
<meta property="og:title" content="About Acme">

Structured data (JSON-LD)

The built-in schema builder covers the major JSON-LD types.

use Laravel\Head\Enums\OfferAvailability;
use Laravel\Head\Facades\Schema;

Head::schema(
    Schema::product()
        ->name($product->name)
        ->offers(
            Schema::offer()
                ->price($product->price)
                ->currency('USD')
                ->availability(OfferAvailability::InStock)
        )
);

The built-in factory methods are article, blogPosting, product, offer, brand, breadcrumbs, faq, organization, person, webPage, and webSite. Unknown factory methods fall back to a generic schema object, so you can represent custom schema.org types too. Breadcrumb items can be added one at a time or in bulk. Positions are assigned automatically in insertion order.

Head::schema(
    Schema::breadcrumbs()->items([
        'Home' => route('home'),
        'Shop' => route('shop.index'),
        'Shoes' => route('shop.category', 'shoes'),
    ])
);

FAQ questions follow the same pattern. Use question() for one, or questions() for many.

Head::schema(
    Schema::faq()->questions([
        'What is Laravel Head?' => 'A fluent API for managing the document head.',
        'Is it free?' => 'Yes, it is open source.',
    ])
);

Custom schema types can be registered explicitly.

use DateTimeInterface;
use Laravel\Head\Facades\Schema;
use Laravel\Head\Schema\SchemaObject;
use Laravel\Head\SchemaType;

#[SchemaType('JobPosting')]
class JobPosting extends SchemaObject
{
    public function title(string $title): static
    {
        return $this->set('title', $title);
    }

    public function datePosted(DateTimeInterface|string $date): static
    {
        return $this->date('datePosted', $date);
    }
}

Schema::register(JobPosting::class);

Wrap-up

laravel/head centralizes the metadata you need for SEO and social sharing across Blade, Livewire, and Inertia. Its five-layer structure — defaults, route, runtime, and error pages — keeps site-wide consistency while still allowing flexible per-page customization.

laravel/head repository

Source code and the latest updates.

Architecture

Database

Eloquent

Security

Events

Mail and Notifications

Payments

Asynchronous Processing

Real-time Communication

Scheduling

Cache and Optimization

Internationalization

Files and Storage

Debugging and Monitoring

Console and CLI

Performance

Frontend

AI Development

Development Environment

Introduction

Resolution priority

Registering defaults

Route metadata

Runtime metadata

Error pages

Open Graph and Twitter Card

PWA, performance, and icons

Theme color

App metadata and icons

Performance and discoverability

Custom tags

Structured data (JSON-LD)

Wrap-up

laravel/head repository

​Introduction

​Resolution priority

​Registering defaults

​Route metadata

​Runtime metadata

​Error pages

​Open Graph and Twitter Card

​PWA, performance, and icons

​Theme color

​App metadata and icons

​Performance and discoverability

​Custom tags

​Structured data (JSON-LD)

​Wrap-up

laravel/head repository

Introduction

Resolution priority

Registering defaults

Route metadata

Runtime metadata

Error pages

Open Graph and Twitter Card

PWA, performance, and icons

Theme color

App metadata and icons

Performance and discoverability

Custom tags

Structured data (JSON-LD)

Wrap-up