Laravel Head — Document <head> Management Package

Introduction

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

composer require laravel/head

Resolution Precedence

Page head data resolves from five layers, listed from lowest to highest priority:

Page defaults
Route group metadata
Route metadata
Runtime metadata
Error metadata

Higher layers replace lower layers field by field. For example, a runtime title replaces the route title without replacing the route description.

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. If no higher layer sets a title, Acme renders as-is. When a higher layer sets a title, the inherited suffix is applied — Head::title('About') renders About - Acme. Pass exact: true for titles that should ignore the inherited prefix or suffix. Canonical URLs use the current request URL. Pass a string for an explicit URL: Head::canonical('/about'). URLs are normalized to https by default; pass forceHttps: false to preserve the request scheme.

Route Metadata

Static pages can define metadata directly on the route:

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

Shared metadata can be applied to a group:

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

Resource and singleton routes are supported too:

Route::resource('posts', PostController::class)->withHead(
    robots: 'index, follow',
);

withHead() stores plain arrays through Laravel’s native route metadata API, keeping it compatible with cached routes.

Supported Properties

Category	Properties
Document	`title`, `description`, `canonical`, `robots`
App metadata	`themeColor`, `applicationName`, `colorScheme`, `referrer`, `viewport`, `appleWebAppTitle`, `webAppCapable`, `appleWebAppStatusBarStyle`
Social	`og`, `ogImage`, `ogVideo`, `ogAudio`, `twitter`, `twitterImage`
Performance	`preload`, `prefetch`, `preconnect`, `dnsPrefetch`
Discovery	`alternates`, `feed`, `icon`, `favicon`, `appleTouchIcon`, `appleTouchStartupImage`, `maskIcon`, `manifest`
Structured data	`schema`
Custom tags	`meta`, `link`

Runtime Metadata

For values that aren’t known until a request arrives — such as a post title — set them 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]);
}

Multiple runtime calls are merged in order. For single-value fields, the later call wins. Repeatable fields keep multiple entries but updating the same key replaces the earlier entry. Conditional metadata can be defined fluently with when() and unless():

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

Error Pages

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 response is rendered for a registered error status, that metadata beats every other layer.

Open Graph and Twitter Cards

Set Open Graph properties with og(), and add repeatable media with dedicated methods:

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 missing og:title and og:description values. For a single OG image with no other attributes, use the image: shorthand on og():

Head::og(
    type: OgType::Website,
    title: $page->title,
    image: $page->og_image_url,
);

Twitter Cards are registered in defaults and automatically render from the same title, description, and image used by Open Graph:

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

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

Individual pages may override Twitter values explicitly:

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

Theme Colors and App Metadata

Theme colors can be set globally, per route, or at runtime. Media-specific colors are supported via the Media enum:

use Laravel\Head\Enums\Media;

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

Laravel Head includes helpers for common browser and app metadata:

use Laravel\Head\Enums\ImageType;

Head::applicationName('Acme')
    ->colorScheme('light dark')
    ->viewport('width=device-width, initial-scale=1')
    ->favicon('/favicon.svg', type: ImageType::Svg)
    ->icon('/favicon-32x32.png', type: ImageType::Png, sizes: '32x32')
    ->appleTouchIcon('/apple-touch-icon.png', sizes: '180x180')
    ->manifest('/site.webmanifest');

Progressive Web Apps

The pwa() helper configures the common <head> tags needed for an installable web app:

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

This renders the application name, web app manifest link, theme color, iOS standalone metadata, and the Apple touch icon in one call.

Performance and Discovery

Laravel Head renders performance hints, pagination links, locale alternates, and feed discovery:

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');

For local assets, preloadAsset() and prefetchAsset() resolve the URL through asset() and detect the as attribute from the file extension. Font preloads automatically include crossorigin:

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

For tags without a dedicated method, use meta() and 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 regular meta tags. For keys that normally use property= such as Open Graph (og:) or article metadata (article:), it switches automatically:

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)

Built-in schema builders cover common 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)
        )
);

Built-in factory methods include article, blogPosting, product, offer, brand, breadcrumbs, faq, organization, person, webPage, and webSite. Unknown factory methods fall back to a generic schema object. Breadcrumb items may be added one at a time or in bulk — positions are assigned automatically:

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

Summary

laravel/head provides a unified, fluent API for managing <head> metadata across Blade, Livewire, and Inertia. Its five-layer resolution model — defaults, route group, route, runtime, and error — keeps site-wide consistency while allowing per-page flexibility, without scattering <meta> tags across templates.

laravel/head repository

Source code and latest updates.

Changelog

Laravel 13

Products

Package Introductions

New Repository Research

Upgrade Guides

Authentication

Frontend

Environment Setup

Laravel Head — Document <head> Management Package

Introduction

Resolution Precedence

Defaults

Route Metadata

Supported Properties

Runtime Metadata

Error Pages

Open Graph and Twitter Cards

Theme Colors and App Metadata

Progressive Web Apps

Performance and Discovery

Custom Tags

Structured Data (JSON-LD)

Summary

laravel/head repository

​Introduction

​Resolution Precedence

​Defaults

​Route Metadata

​Supported Properties

​Runtime Metadata

​Error Pages

​Open Graph and Twitter Cards

​Theme Colors and App Metadata

​Progressive Web Apps

​Performance and Discovery

​Custom Tags

​Structured Data (JSON-LD)

​Summary

laravel/head repository

Introduction

Resolution Precedence

Defaults

Route Metadata

Supported Properties

Runtime Metadata

Error Pages

Open Graph and Twitter Cards

Theme Colors and App Metadata

Progressive Web Apps

Performance and Discovery

Custom Tags

Structured Data (JSON-LD)

Summary