Laravel Head — le package de gestion du <head> d'un document

Introduction

laravel/head est le package officiel qui permet de gérer le <head> d’une application via une API fluent. Il prend en charge le title, les meta, Open Graph, l’URL canonique, les directives robots, les hints de performance et les données structurées, et fonctionne aussi bien avec Blade qu’avec Livewire ou Inertia. La version 0.1.0 est sortie le 28 juillet 2026.

composer require laravel/head

Ordre de résolution

Les données du <head> d’une page sont résolues à partir de cinq couches, de la priorité la plus faible à la plus élevée :

Valeurs par défaut de la page.
Métadonnées d’un groupe de routes.
Métadonnées d’une route.
Métadonnées définies au runtime.
Métadonnées des pages d’erreur.

Chaque couche supérieure remplace la couche inférieure champ par champ. Par exemple, un title défini au runtime remplace celui de la route, mais ne remplace pas la description associée.

Enregistrer les valeurs par défaut

Enregistrez les valeurs par défaut du site dans un 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');
});

La couche « par défaut » est la couche de page la moins prioritaire. Tant qu’aucune couche supérieure ne définit de titre, Acme s’affiche tel quel ; dès qu’une couche supérieure définit un titre, le suffixe hérité s’applique (Head::title('About') devient About - Acme).

Métadonnées de route

Sur les pages statiques, vous pouvez attacher les métadonnées directement à la définition de la route.

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

Il est aussi possible d’appliquer des métadonnées communes à tout un groupe.

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

withHead() stocke un simple tableau via l’API standard des métadonnées de route de Laravel (sous la clé head de ->metadata()), ce qui préserve la compatibilité avec les routes mises en cache.

Métadonnées runtime

Pour des valeurs qui ne sont connues qu’à la réception de la requête (comme le titre d’un billet), utilisez la façade Head au moment de l’exécution.

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

Les métadonnées conditionnelles se déclarent naturellement via when() / unless().

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

Pages d’erreur

Vous pouvez enregistrer des métadonnées par code de statut.

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

Lorsque l’une des pages d’erreur enregistrées est rendue, ces métadonnées prennent le pas sur toutes les autres couches.

Open Graph et Twitter Card

og() configure les propriétés Open Graph, tandis que des méthodes comme ogImage() permettent d’ajouter des images, des vidéos ou de l’audio.

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

Le title et la description du document alimentent automatiquement og:title / og:description s’ils ne sont pas définis explicitement. Une fois Twitter Card enregistrée dans les valeurs par défaut, elle est rendue automatiquement à partir des mêmes title, description et image que 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,
));

Vous pouvez bien sûr surcharger explicitement les valeurs Twitter au cas par cas.

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

PWA, performance et icônes

Le helper pwa() regroupe les balises <head> nécessaires à une application web installable.

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

Theme color

La couleur de thème peut être définie globalement, par route ou au runtime. L’enum Media permet même de spécifier des couleurs différentes selon le média.

use Laravel\Head\Enums\Media;

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

Media inclut également Portrait et Landscape.

Métadonnées d’application et icônes

Laravel Head expose des helpers pour les métadonnées courantes de navigateur et d’application.

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() est un alias de icon() qui accepte les mêmes arguments type, sizes et media.

Performance et découvrabilité

Laravel Head peut aussi générer des hints de performance, des liens de pagination, des variantes de locale et des balises de découverte de flux.

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() résolvent l’URL via le helper asset() et déduisent automatiquement l’attribut as à partir de l’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">

Balises personnalisées

Pour toute balise ne disposant pas d’une méthode dédiée, utilisez 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() utilise name= pour les balises meta classiques, mais bascule automatiquement sur property= pour les clés qui l’exigent (comme Open Graph og: ou les métadonnées d’article article:).

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

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

Données structurées (JSON-LD)

Le builder de schémas intégré couvre les principaux types JSON-LD.

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

Les fabriques intégrées sont article, blogPosting, product, offer, brand, breadcrumbs, faq, organization, person, webPage et webSite. Les fabriques inconnues retombent sur un objet schéma générique, ce qui vous permet de représenter n’importe quel type schema.org personnalisé. Les éléments d’un fil d’Ariane peuvent être ajoutés un par un ou en bloc. La position est attribuée automatiquement dans l’ordre d’ajout.

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

Les questions d’une FAQ suivent le même schéma : question() pour en ajouter une, questions() pour en ajouter plusieurs.

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

Les types de schéma personnalisés peuvent être enregistrés explicitement.

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

Conclusion

laravel/head permet de gérer de manière centralisée les métadonnées nécessaires au SEO et au partage social, aussi bien avec Blade qu’avec Livewire ou Inertia. Sa structure à cinq couches — défauts, groupe de routes, route, runtime et pages d’erreur — préserve la cohérence globale du site tout en permettant une personnalisation fine page par page.

Dépôt laravel/head

Le code source et les dernières informations.

Changelog

Laravel 13

Produits

Présentation des packages

Étude de nouveaux dépôts

Guides de mise à jour

Authentification

Frontend

Configuration de l'environnement

Laravel Head — le package de gestion du <head> d'un document

Introduction

Ordre de résolution

Enregistrer les valeurs par défaut

Métadonnées de route

Métadonnées runtime

Pages d’erreur

Open Graph et Twitter Card

PWA, performance et icônes

Theme color

Métadonnées d’application et icônes

Performance et découvrabilité

Balises personnalisées

Données structurées (JSON-LD)

Conclusion

Dépôt laravel/head

​Introduction

​Ordre de résolution

​Enregistrer les valeurs par défaut

​Métadonnées de route

​Métadonnées runtime

​Pages d’erreur

​Open Graph et Twitter Card

​PWA, performance et icônes

​Theme color

​Métadonnées d’application et icônes

​Performance et découvrabilité

​Balises personnalisées

​Données structurées (JSON-LD)

​Conclusion

Dépôt laravel/head

Introduction

Ordre de résolution

Enregistrer les valeurs par défaut

Métadonnées de route

Métadonnées runtime

Pages d’erreur

Open Graph et Twitter Card

PWA, performance et icônes

Theme color

Métadonnées d’application et icônes

Performance et découvrabilité

Balises personnalisées

Données structurées (JSON-LD)

Conclusion