Laravel Head — document <head> 管理パッケージ

はじめに

laravel/head は、アプリケーションのドキュメント <head> を流暢なAPIで管理するLaravel公式パッケージです。title・meta タグ、Open Graph、canonical URL、robots ディレクティブ、パフォーマンスヒント、構造化データをサポートし、Blade・Livewire・Inertia のいずれでも動作します。2026年7月28日にv0.1.0がリリースされました。

composer require laravel/head

解決の優先順位

ページの head データは、優先度の低い順から次の5つの層で解決されます。

ページのデフォルト
ルートグループのメタデータ
ルートのメタデータ
ランタイムのメタデータ
エラーページのメタデータ

上位の層は下位の層をフィールド単位で上書きします。例えばランタイムで設定した title はルートの title を置き換えますが、description までは置き換えません。

デフォルトの登録

サービスプロバイダーでサイト全体のデフォルトを登録します。

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

デフォルト層は最も優先度が低いページ層です。上位の層で title が設定されない限り Acme がそのまま表示され、上位層が title を設定すると、継承された suffix が適用されます（Head::title('About') は About - Acme になります）。

ルートメタデータ

静的なページはルート定義に直接メタデータを紐付けられます。

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

グループ全体に共通のメタデータを適用することもできます。

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

withHead() は Laravel 標準のルートメタデータAPI（->metadata() の head キー配下）を通じてプレーンな配列を保存するため、キャッシュされたルートとの互換性も保たれます。

ランタイムメタデータ

投稿タイトルのようにリクエストが来るまで分からない値は、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]);
}

条件付きのメタデータは when() / unless() で流暢に記述できます。

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

エラーページ

ステータスコードごとのメタデータも登録できます。

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

登録済みのエラーステータスがレンダリングされる場合、このメタデータは他のどの層よりも優先されます。

Open Graph と Twitter Card

og() で Open Graph プロパティを設定し、ogImage() などのメソッドで画像・動画・音声を追加できます。

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

document の title と description は、未設定の og:title / og:description を自動的に補完します。 Twitter Card はデフォルトに登録しておくだけで、Open Graph と同じ title・description・画像から自動的にレンダリングされます。

use Laravel\Head\Enums\TwitterCard;
use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;

Head::defaults(fn (HeadBuilder $head) => $head->twitter(
    card: TwitterCard::SummaryWithLargeImage,
));

個別のページでTwitterの値を明示的に上書きすることもできます。

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

PWA・パフォーマンス・アイコン

pwa() ヘルパーはインストール可能な Web アプリに必要な <head> タグをまとめて設定します。

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

テーマカラー

テーマカラーはグローバル・ルート・ランタイムのいずれでも設定できます。Media enum を使えばメディア別のテーマカラーも指定できます。

use Laravel\Head\Enums\Media;

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

Media には Portrait と Landscape も含まれます。

アプリメタデータとアイコン

Laravel Head にはブラウザやアプリの一般的なメタデータ用ヘルパーが含まれています。

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() は icon() のエイリアスで、同じ type・sizes・media 引数を受け付けます。

パフォーマンスと発見可能性

Laravel Head はパフォーマンスヒント、ページネーションリンク、ロケール代替表現、フィードの発見用タグもレンダリングできます。

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() は asset() ヘルパーでURLを解決し、拡張子から as 属性を自動検出します。

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

カスタムタグ

専用メソッドがないタグは 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() は通常のmetaタグには name= を使いますが、Open Graph（og:）や記事メタデータ（article:）のように本来 property= を使うキーの場合は自動的に切り替わります。

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

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

構造化データ（JSON-LD）

組み込みのスキーマビルダーは主要な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)
        )
);

組み込みのファクトリーメソッドは article・blogPosting・product・offer・brand・breadcrumbs・faq・organization・person・webPage・webSite です。未知のファクトリーメソッドは汎用のスキーマオブジェクトにフォールバックするため、カスタムのschema.orgタイプも表現できます。パンくずリストの項目は1件ずつ、またはまとめて追加できます。位置は追加順に自動で割り当てられます。

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

FAQの質問も同様のパターンです。question() で1件ずつ、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.',
    ])
);

カスタムのスキーマタイプは明示的に登録できます。

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

まとめ

laravel/head は、Blade・Livewire・Inertia を横断してSEOやソーシャルシェアに必要なメタデータを一元管理できるパッケージです。デフォルト・ルート・ランタイム・エラーページの5層構造により、サイト全体の一貫性を保ちつつページ単位の柔軟なカスタマイズも可能になります。

laravel/head リポジトリ

ソースコードと最新情報はこちら。

Changelog

Laravel 13

プロダクト

パッケージ紹介

新リポジトリ調査

アップグレードガイド

認証

フロントエンド

環境構築

Laravel Head — document <head> 管理パッケージ

はじめに

解決の優先順位

デフォルトの登録

ルートメタデータ

ランタイムメタデータ

エラーページ

Open Graph と Twitter Card

PWA・パフォーマンス・アイコン

テーマカラー

アプリメタデータとアイコン

パフォーマンスと発見可能性

カスタムタグ

構造化データ（JSON-LD）

まとめ

laravel/head リポジトリ

​はじめに

​解決の優先順位

​デフォルトの登録

​ルートメタデータ

​ランタイムメタデータ

​エラーページ

​Open Graph と Twitter Card

​PWA・パフォーマンス・アイコン

​テーマカラー

​アプリメタデータとアイコン

​パフォーマンスと発見可能性

​カスタムタグ

​構造化データ（JSON-LD）

​まとめ

laravel/head リポジトリ

はじめに

解決の優先順位

デフォルトの登録

ルートメタデータ

ランタイムメタデータ

エラーページ

Open Graph と Twitter Card

PWA・パフォーマンス・アイコン

テーマカラー

アプリメタデータとアイコン

パフォーマンスと発見可能性

カスタムタグ

構造化データ（JSON-LD）

まとめ