Get Started

Starter Recipes

On this page

Default server tags
Basic SEO metadata
Social preview metadata
Article metadata
Favicons and theme colors
Web app metadata
See Also

These recipes cover basic SEO, social sharing metadata, blog posts, favicons, and PWA tags.

For a searchable catalog of head tags, see the Zhead Head Tag Database.

Default server tags

The server head adds these defaults unless you create it with disableDefaults: true. You can override them with later entries.

<html lang="en">: Sets the document's default language.
<meta charset="utf-8">: Selects UTF-8 character encoding.
<meta name="viewport" content="width=device-width, initial-scale=1">: Sets the layout viewport to the device width at the initial zoom level.

An HTML charset declaration must appear entirely within the document's first 1024 bytes, which is why it belongs at the start of <head>. See the MDN references for <meta charset> and viewport metadata.

Basic SEO metadata

This recipe sets the document language, title, description, and canonical URL. Add the social preview metadata when links to the page will be shared on other platforms.

A canonical URL is a strong signal, not a directive, and Google may select a different representative URL. Use a self-referencing canonical and keep canonical signals consistent across HTML, redirects, and sitemaps. See Google's canonicalization guidance.

import { useHead, useSeoMeta } from 'unhead'

// [useHead](/docs/head/api/composables/use-head): general head tag management
// [useSeoMeta](/docs/head/api/composables/use-seo-meta): type-safe SEO meta tags
useHead(unheadInstance, {
  htmlAttrs: { lang: 'en-US' }, // BCP 47 language code
  link: [{
    rel: 'canonical',
    href: 'https://www.example.com/about'
  }]
})

useSeoMeta(unheadInstance, {
  title: 'About Us',
  titleTemplate: '%s - Site',
  description: 'Meet the team and learn how the company works.',
})

import { useHead } from 'unhead'

useHead(unheadInstance, {
  htmlAttrs: { lang: 'en-US' }, // BCP 47 language code
  title: 'About Us',
  titleTemplate: '%s - Site',
  meta: [
    {
      name: 'description',
      content: 'Meet the team and learn how the company works.'
    },
    // Add { name: 'robots', content: 'noindex, nofollow' } only when this page should not be indexed.
  ],
  link: [
    {
      rel: 'canonical',
      href: 'https://www.example.com/about'
    }
  ]
})

Additional Open Graph fields

These optional Open Graph properties identify the page type, URL, locale, and site name.

import { useSeoMeta } from 'unhead'

useSeoMeta(unheadInstance, {
  ogType: 'website',
  ogUrl: 'https://www.example.com/about', // should match canonical URL
  ogLocale: 'en_US',
  ogSiteName: 'My Site',
})

SEO tips

Google Search ignores <meta name="keywords">; it has no effect on indexing or ranking.
Avoid duplicate titles and descriptions across your site. If several URLs serve the same content, use <link rel="canonical"> to indicate the preferred URL. Google recommends an absolute URL and may still select another canonical.

Social platforms use Open Graph metadata and platform-specific fields to build link previews. Set the preview title, description, and image explicitly when they should differ from the page's HTML metadata.

import { useSeoMeta } from 'unhead'

useSeoMeta(unheadInstance, {
  // title & descriptions
  ogTitle: 'Travel Keyboard',
  ogDescription: 'A compact mechanical keyboard with hot-swappable switches and Bluetooth pairing.',
  // Legacy X-specific account metadata; these fields are deprecated in the schema
  twitterSite: '@example',
  twitterCreator: '@example',
  // og image
  ogImage: {
    url: 'https://example.com/og-image.png',
    width: 1200,
    height: 630,
    alt: 'Travel Keyboard in its carrying case',
    type: 'image/png'
  },
  // `twitterImage` is deprecated; use `ogImage`
  twitterCard: 'summary_large_image', // or summary
  // Legacy X-specific label and data metadata
  twitterLabel1: 'Price',
  twitterData1: '$50',
  twitterLabel2: 'Read Time',
  twitterData2: '10 min',
})

import { useSeoMeta } from 'unhead'

useSeoMeta(unheadInstance, {
  ogImage: [
    {
      url: 'https://www.example.com/image1.png',
      alt: 'Travel Keyboard viewed from above',
      width: 1200,
      height: 630,
      type: 'image/png'
    },
    {
      url: 'https://www.example.com/image2.png',
      alt: 'Travel Keyboard connected to a tablet',
      width: 1200,
      height: 630,
      type: 'image/png'
    }
  ]
})

Google can also use og:image, Schema.org's primaryImageOfPage, or an image attached to the page's main entity as preferred-image signals for text results and Discover. Selection remains automatic. Choose a relevant, representative, high-resolution image rather than a generic logo or one with an extreme aspect ratio; see Google's preferred-image guidance.

Open Graph defines og:title, og:type, og:image, and og:url as its basic fields. If you provide an image, also provide descriptive og:image:alt text.
Add twitterCard when you need an X-specific card type; the other X-specific fields in this example are retained only for legacy schema compatibility.
Write titles and descriptions for the context in which people will encounter the shared link.

Article metadata

For an article, add publication details to the basic SEO and social preview tags.

import { useHead, useSeoMeta } from 'unhead'

useSeoMeta(unheadInstance, {
  ogType: 'article',
  articlePublishedTime: '2023-04-01T12:00:00Z',
  articleModifiedTime: '2023-05-10T14:45:00Z',
  articleAuthor: ['https://site.com/authors/john-doe'],
  articleSection: 'Technology', // category
  articleTag: ['JavaScript'],
  twitterLabel1: 'Author',
  twitterData1: 'John Doe',
  twitterLabel2: 'Read Time',
  twitterData2: '10 min',
})

// link to previous and next posts
useHead(unheadInstance, {
  link: [
    { rel: 'prev', href: 'https://site.com/blog/previous' },
    { rel: 'next', href: 'https://site.com/blog/next' }
  ]
})

Blog post tips

Combine it with BlogPosting Schema.org to provide more semantic meaning to your page.

Favicons and theme colors

Use icon links for browser and device icons, then set theme colors for supported browser chrome.

import { useHead } from 'unhead'

useHead(unheadInstance, {
  link: [
    { rel: 'icon', href: '/favicon.ico' },
    { rel: 'icon', href: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' },
    { rel: 'apple-touch-icon', sizes: '180x180', href: '/apple-touch-icon.png' },
  ],
  meta: [
    // used on some mobile browsers
    { name: 'theme-color', content: '#0000FF' },
    // choose light or dark (or both, see Light + Dark Mode)
    { name: 'color-scheme', content: 'light dark' },
  ]
})

Use sizes: 'any' for a scalable icon such as SVG. For bitmap icons, either list the sizes the file contains or omit sizes; see MDN's sizes reference.

import { useHead } from 'unhead'

useHead(unheadInstance, {
  meta: [
    { name: 'theme-color', content: '#0000FF', media: '(prefers-color-scheme: light)' },
    { name: 'theme-color', content: '#000000', media: '(prefers-color-scheme: dark)' },
    { name: 'color-scheme', content: 'light dark' }
  ]
})

Favicon tips

An ICO file can contain several bitmap sizes, while sizes="any" indicates a scalable icon such as SVG. See the MDN icon reference.
For Google Search, use a stable, crawlable square favicon. Google requires at least 8×8 pixels and recommends more than 48×48 pixels. See Google's favicon guidelines.
Add an SVG icon alongside the ICO fallback if you want a scalable favicon.

Web app metadata

The manifest link associates the document with a web app manifest. The theme fields affect supported browsers and installed apps; a document-level theme-color can override the manifest value.

import { useHead } from 'unhead'

useHead(unheadInstance, {
  link: [
    { rel: 'manifest', href: '/manifest.json' },
    { rel: 'apple-touch-icon', href: '/apple-touch-icon.png' }
  ],
  meta: [
    { name: 'viewport', content: 'width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=5, viewport-fit=cover' },
    { name: 'theme-color', content: '#0000FF' },
    { name: 'apple-mobile-web-app-capable', content: 'yes' },
    { name: 'apple-mobile-web-app-status-bar-style', content: 'default' }
  ]
})