Laravel Head — paquete para gestionar el <head> del documento

Introducción

laravel/head es el paquete oficial de Laravel que gestiona el <head> del documento de la aplicación mediante una API fluida. Soporta title y etiquetas meta, Open Graph, URL canónica, directivas de robots, hints de rendimiento y datos estructurados, y funciona con Blade, Livewire o Inertia. La v0.1.0 se lanzó el 28 de julio de 2026.

composer require laravel/head

Orden de resolución

Los datos del head de una página se resuelven en las cinco capas siguientes, de menor a mayor prioridad.

Valores por defecto de la página
Metadatos del grupo de rutas
Metadatos de la ruta
Metadatos en runtime
Metadatos de la página de error

Las capas superiores sobrescriben las inferiores campo por campo. Por ejemplo, un title definido en runtime reemplaza al title de la ruta, pero no reemplaza también a la description.

Registrar valores por defecto

Registra los valores por defecto de todo el sitio en 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 capa de valores por defecto es la de menor prioridad. Mientras las capas superiores no definan un title, se muestra Acme tal cual; cuando una capa superior define un title, se aplica el sufijo heredado (Head::title('About') se convierte en About - Acme).

Metadatos de ruta

Las páginas estáticas pueden asociar metadatos directamente a la definición de la ruta.

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

También puedes aplicar metadatos comunes a todo un grupo.

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

withHead() guarda un array plano a través de la API estándar de metadatos de ruta de Laravel (bajo la clave head de ->metadata()), así que se mantiene la compatibilidad con las rutas cacheadas.

Metadatos en runtime

Los valores que solo se conocen al llegar la petición, como el título de una entrada, se establecen en tiempo de ejecución con la fachada 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]);
}

Los metadatos condicionales pueden escribirse de forma fluida con when() / unless().

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

Páginas de error

También puedes registrar metadatos por código de estado.

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

Cuando se renderiza un estado de error registrado, estos metadatos tienen prioridad sobre cualquier otra capa.

Open Graph y Twitter Card

Con og() defines las propiedades de Open Graph y con métodos como ogImage() añades imágenes, vídeos y 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,
    );

El title y la description del documento completan automáticamente los og:title / og:description que no estén definidos. Basta con registrar Twitter Card en los valores por defecto para que se renderice automáticamente a partir del mismo title, description e imagen de 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,
));

También puedes sobrescribir los valores de Twitter explícitamente en una página concreta.

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

PWA, rendimiento e iconos

El helper pwa() configura de una vez las etiquetas del <head> necesarias para una web app instalable.

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

Color del tema

El color del tema puede definirse a nivel global, de ruta o en runtime. Con el enum Media puedes indicar colores de tema específicos por tipo de medio.

use Laravel\Head\Enums\Media;

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

Media también incluye Portrait y Landscape.

Metadatos de la aplicación e iconos

Laravel Head incluye helpers para los metadatos habituales del navegador y de la aplicación.

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() es un alias de icon() y acepta los mismos argumentos type, sizes y media.

Rendimiento y descubribilidad

Laravel Head también puede renderizar hints de rendimiento, enlaces de paginación, alternativas de locale y etiquetas de descubrimiento de feeds.

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() resuelven la URL con el helper asset() y detectan automáticamente el atributo as a partir de la extensión.

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

Etiquetas personalizadas

Las etiquetas que no tienen un método dedicado pueden añadirse 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= para las metaetiquetas normales, pero cambia automáticamente cuando la clave usa por convención property=, como Open Graph (og:) o los metadatos de artículo (article:).

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

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

Datos estructurados (JSON-LD)

El constructor de esquemas integrado cubre los principales tipos de 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)
        )
);

Los métodos factory integrados son article, blogPosting, product, offer, brand, breadcrumbs, faq, organization, person, webPage y webSite. Los métodos factory desconocidos hacen fallback a un objeto de esquema genérico, con lo que también puedes expresar tipos personalizados de schema.org. Los elementos de una lista de breadcrumbs pueden añadirse uno a uno o en bloque. La posición se asigna automáticamente por orden de inserción.

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

Las preguntas de FAQ siguen el mismo patrón. Puedes añadirlas de una en una con question() o en bloque con questions().

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

Los tipos de esquema personalizados pueden registrarse explícitamente.

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

Resumen

laravel/head es un paquete que permite gestionar de forma unificada, y transversal entre Blade, Livewire e Inertia, los metadatos necesarios para SEO y para compartir en redes sociales. Su estructura de 5 capas (defaults, ruta, grupo, runtime y páginas de error) permite mantener la coherencia de todo el sitio y, al mismo tiempo, personalizar cada página con flexibilidad.

Repositorio de laravel/head

El código fuente y la información más reciente están aquí.

Changelog

Laravel 13

Productos

Presentación de paquetes

Análisis de nuevos repositorios

Guías de actualización

Autenticación

Frontend

Configuración del entorno

Laravel Head — paquete para gestionar el <head> del documento

Introducción

Orden de resolución

Registrar valores por defecto

Metadatos de ruta

Metadatos en runtime

Páginas de error

Open Graph y Twitter Card

PWA, rendimiento e iconos

Color del tema

Metadatos de la aplicación e iconos

Rendimiento y descubribilidad

Etiquetas personalizadas

Datos estructurados (JSON-LD)

Resumen

Repositorio de laravel/head

​Introducción

​Orden de resolución

​Registrar valores por defecto

​Metadatos de ruta

​Metadatos en runtime

​Páginas de error

​Open Graph y Twitter Card

​PWA, rendimiento e iconos

​Color del tema

​Metadatos de la aplicación e iconos

​Rendimiento y descubribilidad

​Etiquetas personalizadas

​Datos estructurados (JSON-LD)

​Resumen

Repositorio de laravel/head

Introducción

Orden de resolución

Registrar valores por defecto

Metadatos de ruta

Metadatos en runtime

Páginas de error

Open Graph y Twitter Card

PWA, rendimiento e iconos

Color del tema

Metadatos de la aplicación e iconos

Rendimiento y descubribilidad

Etiquetas personalizadas

Datos estructurados (JSON-LD)

Resumen