Laravel Head — pacchetto per gestire il <head> del documento

Introduzione

laravel/head è il pacchetto ufficiale Laravel che gestisce con un’API fluida il <head> del documento della tua applicazione. Supporta title, meta tag, Open Graph, canonical URL, direttive robots, performance hints e dati strutturati; funziona con Blade, Livewire e Inertia. La v0.1.0 è stata rilasciata il 28 luglio 2026.

composer require laravel/head

Ordine di risoluzione

I dati di head della pagina vengono risolti secondo cinque livelli, dal più basso al più alto in priorità.

Default della pagina
Metadati del gruppo di route
Metadati della route
Metadati a runtime
Metadati delle pagine di errore

I livelli superiori sovrascrivono i livelli inferiori campo per campo. Ad esempio, il title impostato a runtime sostituisce il title della route ma non ne sostituisce la description.

Registrazione dei default

I default a livello di sito si registrano in 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');
});

Il livello dei default è quello con priorità più bassa. Finché nessun livello superiore imposta il title verrà usato Acme così com’è; se un livello superiore imposta il title, verrà applicato il suffisso ereditato (Head::title('About') diventa About - Acme).

Metadati della route

Le pagine statiche possono associare i metadati direttamente alla definizione della route.

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

Puoi applicare metadati comuni a un intero gruppo.

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

withHead() salva un array semplice attraverso l’API standard dei metadati di route di Laravel (sotto la chiave head di ->metadata()), quindi mantiene la compatibilità con le route in cache.

Metadati a runtime

Per valori noti solo alla richiesta — come il titolo di un post — impostali a runtime con la facade Head.

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

I metadati condizionali si esprimono in modo fluido con when() / unless().

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

Pagine di errore

Puoi registrare metadati per singolo status code.

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

Quando viene renderizzato uno degli status di errore registrati, questi metadati hanno la precedenza su qualunque altro livello.

Open Graph e Twitter Card

Con og() imposti le proprietà Open Graph e con metodi come ogImage() aggiungi immagini, video o 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,
    );

title e description del documento popolano automaticamente og:title / og:description se non impostati. Le Twitter Card, una volta registrate nei default, si renderizzano automaticamente usando gli stessi title, description e immagini di 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,
));

Puoi anche sovrascrivere esplicitamente i valori Twitter sulla singola pagina.

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

PWA, performance e icone

L’helper pwa() imposta in blocco i tag <head> necessari per un’app web installabile.

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

Theme color

Il theme color può essere impostato a livello globale, di route o a runtime. Con l’enum Media puoi specificare theme color per media specifici.

use Laravel\Head\Enums\Media;

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

Media include anche Portrait e Landscape.

Metadati e icone dell’app

Laravel Head include helper per i comuni metadati di browser e app.

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() è un alias di icon() e accetta gli stessi argomenti type, sizes e media.

Performance e discoverability

Laravel Head può renderizzare anche performance hints, link di paginazione, alternative di locale e tag per la scoperta dei feed.

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() risolvono l’URL con l’helper asset() e rilevano automaticamente l’attributo as dall’estensione.

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

Tag personalizzati

I tag senza un metodo dedicato si aggiungono con 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() usa name= per i normali meta tag, ma per le chiavi che di norma usano property= (Open Graph og:, metadati di articolo article:) passa automaticamente all’attributo corretto.

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

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

Dati strutturati (JSON-LD)

Lo schema builder integrato copre i principali tipi 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)
        )
);

I metodi factory integrati sono article, blogPosting, product, offer, brand, breadcrumbs, faq, organization, person, webPage e webSite. I factory sconosciuti ricadono su un oggetto schema generico, così puoi rappresentare anche tipi schema.org personalizzati. Gli elementi di una breadcrumb possono essere aggiunti uno per volta o in blocco. La posizione viene assegnata in automatico in base all’ordine.

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

Le domande delle FAQ seguono lo stesso pattern. Con question() aggiungi una domanda alla volta, con questions() più insieme.

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

I tipi di schema personalizzati vanno registrati esplicitamente.

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

Conclusioni

laravel/head è un pacchetto che ti permette di gestire in modo centralizzato i metadati necessari a SEO e condivisione sui social, attraversando Blade, Livewire e Inertia. La struttura a cinque livelli (default, gruppo di route, route, runtime, pagine di errore) preserva la coerenza dell’intero sito e allo stesso tempo lascia flessibilità di personalizzazione pagina per pagina.

Repository laravel/head

Codice sorgente e novità più recenti.

Changelog

Laravel 13

Prodotti

Presentazione dei pacchetti

Analisi di nuovi repository

Guide di aggiornamento

Autenticazione

Frontend

Configurazione dell'ambiente

Laravel Head — pacchetto per gestire il <head> del documento

Introduzione

Ordine di risoluzione

Registrazione dei default

Metadati della route

Metadati a runtime

Pagine di errore

Open Graph e Twitter Card

PWA, performance e icone

Theme color

Metadati e icone dell’app

Performance e discoverability

Tag personalizzati

Dati strutturati (JSON-LD)

Conclusioni

Repository laravel/head

​Introduzione

​Ordine di risoluzione

​Registrazione dei default

​Metadati della route

​Metadati a runtime

​Pagine di errore

​Open Graph e Twitter Card

​PWA, performance e icone

​Theme color

​Metadati e icone dell’app

​Performance e discoverability

​Tag personalizzati

​Dati strutturati (JSON-LD)

​Conclusioni

Repository laravel/head

Introduzione

Ordine di risoluzione

Registrazione dei default

Metadati della route

Metadati a runtime

Pagine di errore

Open Graph e Twitter Card

PWA, performance e icone

Theme color

Metadati e icone dell’app

Performance e discoverability

Tag personalizzati

Dati strutturati (JSON-LD)

Conclusioni