> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # Laravel Head — le package de gestion du d'un document > Présentation de laravel/head, le package officiel qui permet de gérer via une API fluent le title, les meta, Open Graph, l'URL canonique, robots, les hints de performance et les données structurées. Compatible avec Blade, Livewire et Inertia. Publié le 28 juillet 2026. ## Introduction [laravel/head](https://github.com/laravel/head) est le package officiel qui permet de gérer le `` 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. ```bash theme={null} composer require laravel/head ``` ## Ordre de résolution Les données du `` d'une page sont résolues à partir de cinq couches, de la priorité la plus faible à la plus élevée : 1. Valeurs par défaut de la page. 2. Métadonnées d'un groupe de routes. 3. Métadonnées d'une route. 4. Métadonnées définies au runtime. 5. 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. ```mermaid theme={null} graph TD A["Valeurs par défaut de la page"] --> B["Métadonnées
de groupe de routes"] B --> C["Métadonnées de route"] C --> D["Métadonnées runtime"] D --> E["Métadonnées
des pages d'erreur"] E --> F["Sortie finale
du <head>"] ``` ## Enregistrer les valeurs par défaut Enregistrez les valeurs par défaut du site dans un service provider. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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()`. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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 `` nécessaires à une application web installable. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} Head::preloadAsset('fonts/inter.woff2') ->prefetchAsset('images/next.webp'); ``` ```html theme={null} ``` ## Balises personnalisées Pour toute balise ne disposant pas d'une méthode dédiée, utilisez `meta()` / `link()`. ```php theme={null} 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:`). ```php theme={null} Head::meta('description', 'About Acme') ->meta('og:title', 'About Acme'); ``` ```html theme={null} ``` ## Données structurées (JSON-LD) Le builder de schémas intégré couvre les principaux types JSON-LD. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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. ```php theme={null} 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. Le code source et les dernières informations. ## Related topics - [CHANGELOG et gestion des releases de packages](/fr/advanced/package-changelog.md) - [Gestion de la compatibilité de versions de package](/fr/advanced/package-versioning.md) - [Pinning et sécurité de GitHub Actions](/fr/advanced/github-actions-pinning.md) - [Développement de packages Laravel](/fr/advanced/package-development.md) - [Présentation du package Blaze](/fr/blog/blaze-introduction.md)