Laravel Head — Paket zur Verwaltung des Dokument-<head>

Einführung

laravel/head ist ein offizielles Laravel-Paket, das den <head> Ihres Dokuments über eine fluente API verwaltet. Es unterstützt Title- und Meta-Tags, Open Graph, canonical URL, robots-Direktiven, Performance-Hints und strukturierte Daten und funktioniert mit Blade, Livewire und Inertia. Version v0.1.0 wurde am 28. Juli 2026 veröffentlicht.

composer require laravel/head

Auflösungspriorität

Die Head-Daten einer Seite werden – von niedriger zu höherer Priorität – über die folgenden fünf Ebenen aufgelöst.

Standardwerte der Seite
Metadaten der Routen-Gruppe
Metadaten der Route
Laufzeit-Metadaten
Metadaten der Fehlerseite

Höhere Ebenen überschreiben niedrigere feldweise. Ein zur Laufzeit gesetzter Title ersetzt beispielsweise den Title der Route, ersetzt aber nicht deren Description.

Standardwerte registrieren

Registrieren Sie site-weite Standardwerte in einem Service Provider.

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

Die Default-Ebene ist die Seitenebene mit der niedrigsten Priorität. Solange keine übergeordnete Ebene einen Title setzt, wird Acme unverändert angezeigt; setzt eine höhere Ebene einen Title, wird der geerbte Suffix angewendet (Head::title('About') ergibt About - Acme).

Routen-Metadaten

Für statische Seiten können Sie Metadaten direkt an die Routendefinition binden.

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

Sie können auch gemeinsame Metadaten auf eine ganze Gruppe anwenden.

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

withHead() speichert die Daten über die Standard-Routen-Metadaten-API (unter dem head-Schlüssel von ->metadata()) als reines Array, sodass die Kompatibilität mit gecachten Routen erhalten bleibt.

Laufzeit-Metadaten

Werte, die erst zur Requestzeit bekannt sind – etwa der Titel eines Posts – setzen Sie zur Laufzeit über die 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]);
}

Bedingte Metadaten lassen sich mit when() / unless() fluent schreiben.

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

Fehlerseiten

Sie können auch Metadaten je Statuscode registrieren.

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.',
    );
});

Wird ein registrierter Fehlerstatus gerendert, haben diese Metadaten Vorrang vor allen anderen Ebenen.

Open Graph und Twitter Card

Mit og() setzen Sie Open-Graph-Eigenschaften; mit Methoden wie ogImage() fügen Sie Bilder, Videos und Audio hinzu.

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

title und description des Dokuments ergänzen automatisch nicht gesetzte Werte für og:title / og:description. Die Twitter Card wird allein durch das Registrieren in den Defaults automatisch aus demselben Title, derselben Description und denselben Bildern wie Open Graph gerendert.

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

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

Auf einzelnen Seiten können Sie die Twitter-Werte explizit überschreiben.

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

PWA, Performance und Icons

Der pwa()-Helper setzt in einem Rutsch die <head>-Tags, die für eine installierbare Web-App benötigt werden.

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

Theme-Color

Die Theme-Color kann global, pro Route oder zur Laufzeit gesetzt werden. Mit dem Media-Enum lässt sich die Theme-Color auch pro Media Query angeben.

use Laravel\Head\Enums\Media;

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

Media umfasst auch Portrait und Landscape.

App-Metadaten und Icons

Laravel Head enthält Helper für gängige Browser- und App-Metadaten.

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() ist ein Alias für icon() und akzeptiert dieselben Argumente type, sizes und media.

Performance und Auffindbarkeit

Laravel Head kann auch Performance-Hints, Pagination-Links, Locale-Alternativen und Feed-Discovery-Tags rendern.

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() lösen die URL über den asset()-Helper auf und erkennen das as-Attribut automatisch anhand der Dateiendung.

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">

Eigene Tags

Für Tags ohne dedizierte Methode können Sie meta() / link() verwenden.

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

meta() verwendet für gewöhnliche Meta-Tags name=, wechselt aber automatisch, wenn Schlüssel wie Open Graph (og:) oder Article-Metadaten (article:) eigentlich property= verlangen.

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

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

Strukturierte Daten (JSON-LD)

Der eingebaute Schema-Builder deckt die wichtigsten JSON-LD-Typen ab.

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

Die eingebauten Factory-Methoden sind article, blogPosting, product, offer, brand, breadcrumbs, faq, organization, person, webPage und webSite. Unbekannte Factory-Methoden fallen auf ein generisches Schema-Objekt zurück, sodass sich auch benutzerdefinierte schema.org-Typen abbilden lassen. Breadcrumb-Einträge lassen sich einzeln oder gesammelt hinzufügen. Die Position wird anhand der Reihenfolge automatisch vergeben.

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

FAQ-Fragen folgen einem ähnlichen Muster. Mit question() fügen Sie einzelne Fragen hinzu, mit questions() mehrere gleichzeitig.

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.',
    ])
);

Eigene Schema-Typen können explizit registriert werden.

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

Fazit

laravel/head ist ein Paket, mit dem sich die für SEO und Social Sharing benötigten Metadaten über Blade, Livewire und Inertia hinweg zentral verwalten lassen. Die fünfschichtige Struktur aus Standardwerten, Routen-Metadaten, Laufzeit-Metadaten und Fehlerseiten sorgt für Konsistenz über die gesamte Site und erlaubt gleichzeitig flexible seitenspezifische Anpassungen.

laravel/head Repository

Quellcode und aktuelle Informationen hier.

Changelog

Laravel 13

Produkte

Paketvorstellungen

Untersuchung neuer Repositories

Upgrade-Anleitungen

Authentifizierung

Frontend

Einrichtung der Umgebung

Laravel Head — Paket zur Verwaltung des Dokument-<head>

Einführung

Auflösungspriorität

Standardwerte registrieren

Routen-Metadaten

Laufzeit-Metadaten

Fehlerseiten

Open Graph und Twitter Card

PWA, Performance und Icons

Theme-Color

App-Metadaten und Icons

Performance und Auffindbarkeit

Eigene Tags

Strukturierte Daten (JSON-LD)

Fazit

laravel/head Repository

​Einführung

​Auflösungspriorität

​Standardwerte registrieren

​Routen-Metadaten

​Laufzeit-Metadaten

​Fehlerseiten

​Open Graph und Twitter Card

​PWA, Performance und Icons

​Theme-Color

​App-Metadaten und Icons

​Performance und Auffindbarkeit

​Eigene Tags

​Strukturierte Daten (JSON-LD)

​Fazit

laravel/head Repository

Einführung

Auflösungspriorität

Standardwerte registrieren

Routen-Metadaten

Laufzeit-Metadaten

Fehlerseiten

Open Graph und Twitter Card

PWA, Performance und Icons

Theme-Color

App-Metadaten und Icons

Performance und Auffindbarkeit

Eigene Tags

Strukturierte Daten (JSON-LD)

Fazit