> ## 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 > Learn how to use Laravel Head to manage the document across Blade, Livewire, and Inertia, including titles, meta tags, Open Graph, canonical URLs, robots directives, performance hints, and structured data. ## Introduction [laravel/head](https://github.com/laravel/head) is the official Laravel package for managing your application's document `` 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. ```bash theme={null} composer require laravel/head ``` ## Resolution priority The head data for a page is resolved through the following five layers, from lowest to highest priority. 1. Page defaults 2. Route group metadata 3. Route metadata 4. Runtime metadata 5. 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. ```mermaid theme={null} graph TD A["Page defaults"] --> B["Route group
metadata"] B --> C["Route metadata"] C --> D["Runtime metadata"] D --> E["Error page
metadata"] E --> F["Final
<head> output"] ``` ## Registering defaults Register site-wide defaults in a 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'); }); ``` 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. ```php theme={null} Route::view('/contact', 'contact') ->name('contact') ->withHead( title: 'Contact Us', description: 'Get in touch.', ); ``` You can also apply metadata common to a whole group. ```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()` 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. ```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]); } ``` Conditional metadata is expressed fluently with `when()` / `unless()`. ```php theme={null} Head::title($post->title) ->when($post->isDraft(), fn ($head) => $head->hiddenFromRobots()); ``` ## Error pages You can also register metadata for each status code. ```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.', ); }); ``` 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()`. ```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, ); ``` 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. ```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, )); ``` You can also explicitly override the Twitter values on individual pages. ```php theme={null} Head::twitter(title: $post->social_title) ->twitterImage($post->social_image_url, alt: $post->title); ``` ## PWA, performance, and icons The `pwa()` helper sets the `` tags you need for an installable web app in one call. ```php theme={null} 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. ```php theme={null} 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. ```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()` 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. ```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()` resolve the URL with the `asset()` helper and detect the `as` attribute from the extension. ```php theme={null} Head::preloadAsset('fonts/inter.woff2') ->prefetchAsset('images/next.webp'); ``` ```html theme={null} ``` ## Custom tags Tags without a dedicated method can be added with `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()` uses `name=` for ordinary meta tags, but automatically switches for keys that should use `property=`, such as Open Graph (`og:`) or article metadata (`article:`). ```php theme={null} Head::meta('description', 'About Acme') ->meta('og:title', 'About Acme'); ``` ```html theme={null} ``` ## Structured data (JSON-LD) The built-in schema builder covers the major JSON-LD types. ```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) ) ); ``` 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. ```php theme={null} 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. ```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.', ]) ); ``` Custom schema types can be registered explicitly. ```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); ``` ## 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. Source code and the latest updates. ## Related topics - [HTTP client](/en/http-client.md) - [CSRF protection](/en/csrf.md) - [Google Sheets API for Laravel](/en/packages/laravel-google-sheets/index.md) - [Laravel MCP](/en/mcp.md) - [Responses](/en/responses.md)