Unhead

https://unhead.unjs.io/docs
Admin
Unhead is a full-stack document head manager for JavaScript frameworks that optimizes SEO, tags,...
Tokens:179,074
Snippets:2,273
Trust Score:8.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Complete SEO Setup

Source: https://unhead.unjs.io/docs/head/api/composables/use-seo-meta

Comprehensive example covering basic SEO, Open Graph, and Twitter card metadata.

```ts
import { useSeoMeta } from '@unhead/dynamic-import'

useSeoMeta({
  // Basic SEO
  title: 'Product Name - Your Brand',
  description: 'Detailed product description optimized for search engines.',

  // Open Graph
  ogTitle: 'Product Name - Your Brand',
  ogDescription: 'Engaging description for social media shares.',
  ogImage: 'https://example.com/product-social.jpg',
  ogUrl: 'https://example.com/products/my-product',
  ogType: 'website',
  ogSiteName: 'Your Brand',

  // Twitter
  twitterCard: 'summary_large_image',
})
```

--------------------------------

### HowTo JSON-LD Example

Source: https://unhead.unjs.io/docs/schema-org/api/schema/how-to

A basic JSON-LD structure for a HowTo guide, including steps and total time estimation.

```json
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Tie a Tie",
  "step": [
    {
      "@type": "HowToStep",
      "text": "Drape the tie around your neck with the wide end on your right, about 1/3 longer than the narrow end.",
      "image": "https://example.com/step1.jpg"
    },
    {
      "@type": "HowToStep",
      "text": "Cross the wide end over the narrow end, then bring it underneath.",
      "image": "https://example.com/step2.jpg"
    }
  ],
  "totalTime": "PT5M"
}
```

--------------------------------

### Setup VueHeadMixin for Client and Server

Source: https://unhead.unjs.io/docs/vue/head/guides/core-concepts/options-api

Install VueHeadMixin in both client and server entry points to enable Options API support.

```ts
import { createApp } from './main'
import { createHead, VueHeadMixin } from '@unhead/vue/client'

const { app } = createApp()
const head = createHead()
app.use(head)
app.mixin(VueHeadMixin)

app.mount('#app')
```

```ts
import { createApp } from './main'
import { createHead, VueHeadMixin } from '@unhead/vue/server'

const { app } = createApp()
const head = createHead()
app.use(head)
app.mixin(VueHeadMixin)

// Render `app` with Vue's server renderer.
```

--------------------------------

### Define a setup function-based Unhead plugin

Source: https://unhead.unjs.io/docs/head/api/plugins

Use a setup function to access the Unhead instance. Provide a static key as the second argument to enable deduplication.

```ts
import { defineHeadPlugin } from 'unhead/plugins'
import { resolveTags } from 'unhead/utils'

export const myPlugin = defineHeadPlugin(head => ({
  key: 'my-plugin',
  hooks: {
    'entries:updated': () => {
      const tags = resolveTags(head)
      console.log('Current tags:', tags)
    },
  },
}), 'my-plugin')
```

--------------------------------

### Install @unhead/schema-org package

Source: https://unhead.unjs.io/docs/angular/schema-org/guides/get-started/installation

Install the required package using your preferred package manager.

```bash
yarn add @unhead/schema-org
```

```bash
npm install @unhead/schema-org
```

```bash
pnpm add @unhead/schema-org
```

--------------------------------

### Install @unhead/eslint-plugin

Source: https://unhead.unjs.io/docs/head/guides/eslint-plugin

Add the plugin as a development dependency to your project.

```bash
pnpm add -D @unhead/eslint-plugin
```

--------------------------------

### Install Playwright Dependencies

Source: https://unhead.unjs.io/docs/head/guides/get-started/single-page-applications

Install the necessary Playwright packages and browser binaries for the prerendering script.

```bash
pnpm add -D playwright
pnpm exec playwright install chromium
```

--------------------------------

### Configure social preview images

Source: https://unhead.unjs.io/docs/angular/head/api/composables/use-seo-meta

Examples demonstrating how to provide appropriate social preview images and dimensions.

```javascript
// A small icon is unlikely to work well as a large social preview
useSeoMeta({
  twitterCard: 'summary_large_image',
  ogImage: 'https://example.com/small-icon.png',
})

// Supply a purpose-built social image and its dimensions
useSeoMeta({
  twitterCard: 'summary_large_image',
  ogImage: {
    url: 'https://example.com/social-card.jpg',
    width: 1200,
    height: 630,
    alt: 'Product preview',
  },
})
```

--------------------------------

### Install Unhead CLI

Source: https://unhead.unjs.io/docs/typescript/head/guides/tooling/cli

Add the CLI package as a development dependency to your project.

```bash
pnpm add -D @unhead/cli
```

--------------------------------

### Swap Dependencies

Source: https://unhead.unjs.io/docs/react/head/guides/get-started/migrate-from-react-helmet

Commands to remove the legacy package and install the Unhead React package.

```bash
npm remove react-helmet
npm install @unhead/react
```

--------------------------------

### Minimal Product Schema Example

Source: https://unhead.unjs.io/docs/schema-org/api/schema/product

A basic implementation of defineProduct requiring only the name and image properties.

```ts
defineProduct({
  name: 'Guide To Vue.js',
  image: '/vuejs-book.png',
})
```

--------------------------------

### Manual Script Warmup

Source: https://unhead.unjs.io/docs/angular/head/api/composables/use-script

Example of manually triggering a preconnect warmup strategy for a script.

```typescript
const script = useScript('https://example.com/widget.js', {
  trigger: 'manual',
})

script.warmup('preconnect')
```

--------------------------------

### Configure Open Graph metadata

Source: https://unhead.unjs.io/docs/angular/head/api/composables/use-seo-meta

Examples showing minimal and richer Open Graph metadata configurations.

```javascript
// Minimal preview metadata
useSeoMeta({
  ogTitle: 'My Page',
  ogDescription: 'Description'
})

// Richer preview metadata
useSeoMeta({
  ogTitle: 'My Page',
  ogDescription: 'Description',
  ogImage: 'https://example.com/og.jpg',
  ogUrl: 'https://example.com/page',
  ogType: 'website',
})
```

--------------------------------

### Quick Start with useSchemaOrg

Source: https://unhead.unjs.io/docs/nuxt/schema-org/guides/get-started/overview

Initializes a Schema.org graph using the defineArticle helper to generate structured data for a blog post.

```typescript
import { defineArticle, useSchemaOrg } from '#imports'

// Generates an Article node and resolves its image and publication date
useSchemaOrg([
  defineArticle({
    headline: 'My Blog Post',
    image: '/images/post.jpg',
    datePublished: new Date(),
  })
])
```

--------------------------------

### Tree-shaking transformation example

Source: https://unhead.unjs.io/docs/head/guides/build-plugins/tree-shaking

Demonstrates how the build process removes server-only composables like useSchemaOrg from the client bundle.

```ts
useHead({ title: 'My Page' })

useSchemaOrg([
  defineWebPage({ name: 'My Page' }),
])
```

```ts
useHead({ title: 'My Page' })
```

--------------------------------

### Expected JSON-LD output

Source: https://unhead.unjs.io/docs/schema-org/guides/recipes/blog

Example of the resulting JSON-LD structure generated by the configuration.

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": ["Article", "BlogPosting"],
      "@id": "https://example.com/blog/my-post#article",
      "headline": "My Article",
      "image": { "@id": "https://example.com/#/schema/image/1" },
      "datePublished": "2020-02-01T00:00:00.000Z",
      "dateModified": "2020-02-01T00:00:00.000Z",
      "author": [
        { "@id": "https://example.com/#/schema/person/1" },
        { "@id": "https://example.com/#/schema/person/2" }
      ],
      "thumbnailUrl": "https://example.com/photos/16x9/photo.jpg"
    },
    {
      "@type": "Person",
      "@id": "https://example.com/#/schema/person/2",
      "name": "Jane Doe",
      "url": "https://janedoe.com"
    },
    {
      "@type": "Person",
      "@id": "https://example.com/#/schema/person/1",
      "name": "John Doe",
      "url": "https://johndoe.com"
    },
    {
      "@type": "ImageObject",
      "@id": "https://example.com/#/schema/image/1",
      "contentUrl": "https://example.com/photos/16x9/photo.jpg",
      "url": "https://example.com/photos/16x9/photo.jpg"
    }
  ]
}
```

--------------------------------

### JSON-LD SoftwareApplication Example

Source: https://unhead.unjs.io/docs/schema-org/api/schema/software-app

A standard JSON-LD representation of a software application including pricing and aggregate ratings.

```json
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Photo Editor Pro",
  "operatingSystem": "Windows, macOS",
  "applicationCategory": "DesignApplication",
  "offers": {
    "@type": "Offer",
    "price": "9.99",
    "priceCurrency": "USD"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "ratingCount": 1250
  }
}
```

--------------------------------

### Importing and using useSeoMeta in React

Source: https://unhead.unjs.io/docs/react/head/api/composables/use-seo-meta

Shows the required import from @unhead/react and a typical usage example with various SEO fields.

```javascript
import { useSeoMeta } from '@unhead/react'

useSeoMeta({
  title: 'About',
  description: 'My about page',
  ogDescription: 'Still about my about page',
  ogTitle: 'About',
  ogImage: 'https://example.com/image.png',
  twitterCard: 'summary_large_image',
})
```

--------------------------------

### HowToSimple Interface

Source: https://unhead.unjs.io/docs/schema-org/api/schema/how-to

Defines the structure for a HowTo guide, including metadata like total time, supplies, and steps.

```ts
/**
 * Instructions that explain how to achieve a result by performing a sequence of steps.
 */
export interface HowToSimple extends Thing {
  /**
   * A string describing the guide.
   */
  name: string
  /**
   * An array of howToStep objects
   */
  step: NodeRelations<HowToStep | string>[]
  /**
   * The total time required to perform all instructions or directions (including time to prepare the supplies),
   * in ISO 8601 duration format.
   */
  totalTime?: string
  /**
   * Introduction or description content relating to the HowTo guide.
   */
  description?: string
  /**
   * The language code for the guide; e.g., en-GB.
   */
  inLanguage?: string
  /**
   * The estimated cost of the supplies consumed when performing instructions.
   */
  estimatedCost?: string | unknown
  /**
   * Image of the completed how-to.
   */
  image?: NodeRelations<ImageObject | string>
  /**
   * A supply consumed when performing instructions or a direction.
   */
  supply?: string | unknown
  /**
   * An object used (but not consumed) when performing instructions or a direction.
   */
  tool?: string | unknown
  /**
   * A video of the how-to. Follow the list of required and recommended Video properties.
   * Mark steps of the video with hasPart.
   */
  video?: NodeRelations<VideoObject | string>
  /**
   * The time required to prepare for the how-to, in ISO 8601 duration format.
   */
  prepTime?: string
  /**
   * The time it takes to perform the how-to, in ISO 8601 duration format.
   */
  performTime?: string
  /**
   * The quantity that results from performing the how-to.
   */
  yield?: string
}
```

--------------------------------

### Detailed Product Schema with Offers and Reviews

Source: https://unhead.unjs.io/docs/schema-org/api/schema/product

An advanced example including pricing offers, aggregate ratings, and specific user reviews.

```ts
defineProduct({
  name: 'Ergonomic Desk Chair',
  image: '/product.png',
  offers: [
    { price: 50 },
  ],
  aggregateRating: {
    ratingValue: 88,
    bestRating: 100,
    ratingCount: 20,
  },
  review: [
    {
      name: 'Comfortable and easy to assemble.',
      author: {
        name: 'Harlan Wilton',
      },
      reviewRating: {
        ratingValue: 5,
      },
    },
  ],
})
```

--------------------------------

### Replace the Package

Source: https://unhead.unjs.io/docs/vue/head/guides/get-started/migrate-from-vueuse-head

Remove the old dependency and install the new @unhead/vue package.

```bash
npm remove @vueuse/head
npm install @unhead/vue
```

--------------------------------

### HowToStepSimple Interface

Source: https://unhead.unjs.io/docs/schema-org/api/schema/how-to

Defines the structure for an individual step within a HowTo guide.

```ts
export interface HowToStepSimple extends Thing {
  /**
   * A link to a fragment identifier (an 'ID anchor') of the individual step
   * (e.g., https://www.example.com/example-page/#recipe-step-5).
   */
  url?: string
  /**
   * The instruction string
   * ("e.g., "Bake at 200*C for 40 minutes, or until golden-brown, stirring periodically throughout").
   */
  text: string
  /**
   * The word or short phrase summarizing the step (for example, "Attach wires to post" or "Dig").
   * Don't use non-descriptive text (for example, "Step 1: [text]") or other form of step number (for example, "1. [text]").
   */
  name?: string
  /**
   * An image representing the step, referenced by ID.
   */
  image?: NodeRelations<ImageObject | string>
  /**
   * A video for this step or a clip of the video.
   */
  video?: NodeRelations<VideoObject | string>
  /**
   * A list of detailed substeps, including directions or tips.
   */
  itemListElement?: NodeRelations<HowToDirection | string>[]
}
```

--------------------------------

### Unhead defineSoftwareApp Example

Source: https://unhead.unjs.io/docs/schema-org/api/schema/software-app

Using the Unhead helper function to define a software application schema programmatically.

```ts
defineSoftwareApp({
  name: 'Angry Birds',
  operatingSystem: 'ANDROID',
  applicationCategory: 'GameApplication',
  aggregateRating: {
    ratingValue: '4.6',
    ratingCount: 8864,
  },
  offers: {
    price: '1.00',
    priceCurrency: 'USD',
  },
})
```

--------------------------------

### LocalBusiness JSON-LD Example

Source: https://unhead.unjs.io/docs/schema-org/api/schema/local-business

A basic JSON-LD structure for a LocalBusiness, including name, address, telephone, and opening hours.

```json
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Dave's Steak House",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "148 W 51st St",
    "addressLocality": "New York",
    "addressRegion": "NY",
    "postalCode": "10019",
    "addressCountry": "US"
  },
  "telephone": "+12122459600",
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "opens": "11:30",
      "closes": "23:00"
    }
  ]
}
```

--------------------------------

### Avoid redundant SEO metadata

Source: https://unhead.unjs.io/docs/angular/head/api/composables/use-seo-meta

Examples showing how to avoid manual duplication of description fields by using plugins.

```javascript
// Repeated values are harder to keep in sync
useSeoMeta({
  description: 'My description',
  ogDescription: 'My description',
})

// Or install InferSeoMetaPlugin and let it generate matching fallbacks
useSeoMeta({
  description: 'SEO-optimized description for search',
})
```

--------------------------------

### Importing and using useSeoMeta

Source: https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta

Shows the required import and a more comprehensive example of defining various SEO and social media meta tags.

```typescript
import { useSeoMeta } from 'unhead'

useSeoMeta(unheadInstance, {
  title: 'About',
  description: 'My about page',
  ogDescription: 'Still about my about page',
  ogTitle: 'About',
  ogImage: 'https://example.com/image.png',
  twitterCard: 'summary_large_image',
})
```

--------------------------------

### Configure Open Graph Metadata

Source: https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta

Examples showing minimal versus richer Open Graph metadata configurations for social previews.

```typescript
// Minimal preview metadata
useSeoMeta(unheadInstance, {
  ogTitle: 'My Page',
  ogDescription: 'Description'
})

// Richer preview metadata
useSeoMeta(unheadInstance, {
  ogTitle: 'My Page',
  ogDescription: 'Description',
  ogImage: 'https://example.com/og.jpg',
  ogUrl: 'https://example.com/page',
  ogType: 'website',
})
```

--------------------------------

### useScript(input, options?)

Source: https://unhead.unjs.io/docs/svelte/head/api/composables/use-script

Initializes a script loading instance. Framework packages inject the head instance automatically.

```APIDOC
## useScript(input, options?)

### Description
Initializes the loading of an external script. Returns a ScriptInstance controller.

### Parameters
- **input** (string) - The URL of the script to load.
- **options** (object) - Configuration options including trigger settings.
```

--------------------------------

### SSR Marker Handler Example

Source: https://unhead.unjs.io/docs/angular/head/guides/core-concepts/dom-event-handling

Example of how a function handler is rendered as a marker during server-side rendering.

```html
<script onload="this.dataset.onloadfired = true"></script>
```

--------------------------------

### useScript(input, options?)

Source: https://unhead.unjs.io/docs/head/api/composables/use-script

Initializes a script instance. The input is the script URL, and options allow for configuration such as trigger strategies.

```APIDOC
## useScript(input, options?)

### Description
Initializes a script instance for dynamic loading. Framework packages automatically inject the head instance, while core usage requires passing it as the first argument.

### Parameters
- **input** (string) - Required - The URL of the script to load.
- **options** (object) - Optional - Configuration options including trigger settings.
```

--------------------------------

### Detailed Service Example

Source: https://unhead.unjs.io/docs/schema-org/api/schema/service

A comprehensive example including sub-types, multiple service areas, ratings, and reviews.

```ts
defineService({
  'name': 'Professional Consulting Services',
  '@type': 'FinancialService',
  'serviceType': 'Financial Consulting',
  'description': 'Expert financial advisory and consulting for businesses',
  'url': 'https://example.com/services/consulting',
  'provider': {
    '@type': 'Organization',
    name: 'Expert Consultants LLC',
    url: 'https://example.com',
  },
  'areaServed': ['United States', 'Canada', 'United Kingdom'],
  'category': 'Consulting',
  'image': 'https://example.com/services/consulting-hero.jpg',
  'offers': {
    price: 250,
    priceCurrency: 'USD',
    description: 'Hourly consulting rate',
  },
  'aggregateRating': {
    ratingValue: 4.8,
    ratingCount: 120,
  },
  'review': [
    {
      author: 'Jane Smith',
      reviewRating: {
        ratingValue: 5,
      },
      reviewBody: 'Excellent service, highly recommended!',
    },
  ],
  'termsOfService': 'https://example.com/terms',
  'slogan': 'Your success is our mission',
})
```

--------------------------------

### Usage Example

Source: https://unhead.unjs.io/docs/head/api/hooks/tags-after-resolve

An example of using the tags:afterResolve hook to validate integrity attributes on script tags.

```APIDOC
## Usage Example

```ts
import { defineHeadPlugin } from '@unhead/dynamic-import/plugins'

const integrityManagedScripts = new Set([
  'https://cdn.example.com/widget/4.2.0/widget.min.js',
])

export const reportMissingIntegrityPlugin = defineHeadPlugin({
  key: 'report-missing-integrity',
  hooks: {
    'tags:afterResolve': ({ tags }) => {
      for (const tag of tags) {
        if (tag.tag === 'script' && integrityManagedScripts.has(tag.props.src) && !tag.props.integrity)
          console.warn(`Integrity-managed script has no integrity attribute: ${tag.props.src}`)
      }
    }
  }
})
```
```

--------------------------------

### Configure script warmup strategy

Source: https://unhead.unjs.io/docs/angular/head/guides/core-concepts/loading-scripts

Sets a resource hint strategy during script initialization to optimize network performance.

```javascript
useScript('https://example.com/sdk.js', {
  trigger: 'manual',
  warmupStrategy: 'preconnect'
})
```

--------------------------------

### Async Context Error Example

Source: https://unhead.unjs.io/docs/vue/head/guides/core-concepts/reactivity-and-context

Shows an example where Vue loses component context after an async operation, causing useHead to throw an error.

```vue
<script setup lang="ts">
import { useHead } from '@unhead/vue'
import { onMounted } from 'vue'

onMounted(async () => {
  await someAsyncOperation()
  // This will throw an error
  useHead({
    title: 'My Title'
  })
})
</script>
```

--------------------------------

### Initialize a script with API proxying

Source: https://unhead.unjs.io/docs/head/api/composables/use-script

Use the use option to expose a third-party SDK API, allowing calls to be queued and replayed once the script resolves.

```ts
import { useScript } from '@unhead/dynamic-import'

interface AnalyticsApi {
  track: (event: string) => void
}

const analytics = useScript<AnalyticsApi>('https://example.com/analytics.js', {
  use: () => window.analytics,
})

// Recorded now and replayed after the API resolves.
analytics.proxy.track('pageview')
```

--------------------------------

### HTML document structure

Source: https://unhead.unjs.io

Example of a basic HTML document structure.

```html
<!DOCTYPE html>  
<html class="light">  
  <head>  
    <title>Hello World</title>  
  </head>  
  <body>  
  <!-- Your app -->  
  </body>  
</html>
```

--------------------------------

### Abridged JSON-LD Output

Source: https://unhead.unjs.io/docs/schema-org/guides/recipes/faq

Example of the generated JSON-LD output for a FAQ page.

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": ["WebPage", "FAQPage"],
      "@id": "https://example.com/faq#webpage",
      "name": "FAQ",
      "url": "https://example.com/faq",
      "mainEntity": [
        { "@id": "https://example.com/faq#/schema/question/1" }
      ]
    },
    {
      "@id": "https://example.com/faq#/schema/question/1",
      "@type": "Question",
      "name": "How long does delivery take?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Most orders arrive within three to five business days."
      }
    }
  ]
}
```

--------------------------------

### Example rendered title element

Source: https://unhead.unjs.io/docs/angular/head/guides/core-concepts/titles

The resulting HTML output for a page title.

```html
<head>
  <title>Mastering Titles · My App</title>
</head>
```

--------------------------------

### HTML Structure for How-To Content

Source: https://unhead.unjs.io/docs/schema-org/guides/recipes/how-to

A template for organizing instructional content in HTML to facilitate structured data mapping.

```html
<div>
  <h1>How to Build a Desk</h1>
  <p>A step-by-step guide to building a home office desk.</p>

  <div>
    <h2>What You'll Need</h2>
    <ul>
      <li>Wood panels</li>
      <li>Screws</li>
      <li>Hammer</li>
      <li>Nails</li>
    </ul>

    <h2>Tools</h2>
    <ul>
      <li>Screwdriver</li>
      <li>Power drill</li>
      <li>Tape measure</li>
    </ul>
  </div>

  <div>
    <h2>Steps</h2>

    <div>
      <h3>1. Gather materials</h3>
      <img src="/images/desk-materials.jpg" alt="Materials for desk building" />
      <p>Collect all necessary supplies and tools.</p>
    </div>

    <div>
      <h3>2. Cut wood panels</h3>
      <img src="/images/cutting-panels.jpg" alt="Cutting wood panels" />
      <p>Cut the wood panels to the proper dimensions.</p>
    </div>

    <!-- Additional steps... -->
  </div>
</div>
```

--------------------------------

### Define a Product with Schema.org

Source: https://unhead.unjs.io/docs/schema-org/guides/recipes/e-commerce

Use defineProduct to create a product node with essential details like name, description, images, and pricing offers.

```ts
import { defineProduct, useSchemaOrg } from '@unhead/schema-org/@framework'

useSchemaOrg([
  defineProduct({
    name: 'Schema.org Book',
    description: 'Discover how to use Schema.org',
    image: [
      'https://example.com/photos/16x9/photo.jpg'
    ],
    offers: [
      { price: 50 },
    ],
  })
])
```

--------------------------------

### Initialize CanonicalPlugin

Source: https://unhead.unjs.io/docs/head/guides/plugins/canonical

Register the plugin in your head configuration with the required canonical host.

```ts
import { CanonicalPlugin } from '@unhead/dynamic-import/plugins'

const head = createHead({
  plugins: [
    CanonicalPlugin({
      canonicalHost: 'https://mysite.com'
    })
  ]
})
```

--------------------------------

### Define a minimal Dataset

Source: https://unhead.unjs.io/docs/schema-org/api/schema/dataset

A basic example showing the minimum required properties for a Dataset.

```ts
defineDataset({
  name: 'Global Temperature Data 2000-2024',
  description: 'Daily temperature measurements from weather stations worldwide',
})
```

--------------------------------

### Add time information to How-To

Source: https://unhead.unjs.io/docs/schema-org/guides/recipes/how-to

Specify performTime and totalTime using the ISO 8601 duration format.

```ts
import { defineHowTo, useSchemaOrg } from '@unhead/schema-org/@framework'

useSchemaOrg([
  defineHowTo({
    name: 'How to Make Pancakes',
    performTime: 'PT20M', // 20 minutes performing the instructions
    totalTime: 'PT30M', // 30 minutes in ISO 8601 duration format
    step: [
      {
        name: 'Mix ingredients',
        text: 'Combine flour, milk, eggs, and sugar in a bowl.'
      },
      {
        name: 'Cook pancakes',
        text: 'Pour batter onto hot griddle and flip when bubbles form.'
      }
    ]
  })
])
```

--------------------------------

### useHead(input, options)

Source: https://unhead.unjs.io/docs/head/api/composables/use-head

Initializes a head entry with optional configuration for lifecycle hooks.

```APIDOC
## useHead(input, options)

### Description
Registers head tags for the current context. The `onRendered` option allows executing logic after DOM updates occur.

### Parameters
- **input** (Object) - Required - The head tags to apply (e.g., title, meta).
- **options** (Object) - Optional - Configuration object including `onRendered` callback.

### Example
```ts
useHead({
  title: 'My Page',
}, {
  onRendered({ renders }) {
    console.log('DOM updated');
  }
})
```

--------------------------------

### Visible breadcrumb navigation HTML

Source: https://unhead.unjs.io/docs/schema-org/guides/recipes/breadcrumbs

Example of HTML structure that corresponds to the breadcrumb structured data.

```html
<ul>
  <li>
    <a href="/">Home</a>
    <span>/</span>
  </li>
  <li>
    <a href="/blog">Articles</a>
    <span>/</span>
  </li>
  <li>
    <span>How do breadcrumbs work</span>
  </li>
</ul>
```

--------------------------------

### Basic WebPage Definition

Source: https://unhead.unjs.io/docs/schema-org/api/schema/webpage

A simple example of defining a WebPage with a name and a primary image reference.

```ts
defineWebPage({
  name: 'Page Title',
  primaryImageOfPage: '/image.jpg',
})
```

--------------------------------

### Configure Client-Side Rendering

Source: https://unhead.unjs.io/docs/react/head/guides/get-started/installation

Initialize the head instance and wrap the application with UnheadProvider in the client entry file.

```tsx
import { createHead, UnheadProvider } from '@unhead/react/client'
import { StrictMode } from 'react'
import { hydrateRoot } from 'react-dom/client'
import App from './App'
import './index.css'

const head = createHead()

hydrateRoot(
  document.getElementById('root') as HTMLElement,
  <StrictMode>
    <UnheadProvider value={head}>
      <App />
    </UnheadProvider>
  </StrictMode>,
)
```

--------------------------------

### head.use

Source: https://unhead.unjs.io/docs/head/api/plugins

Registers a plugin with an existing Unhead instance.

```APIDOC
## head.use(plugin)

### Description
Registers a plugin instance to the Unhead head object. This can be called after the head instance has been created.

### Parameters
- **plugin** (HeadPlugin) - Required - The plugin object to register.

### Usage Example
```ts
head.use(myPlugin)
```
```

--------------------------------

### Define a detailed Dataset

Source: https://unhead.unjs.io/docs/schema-org/api/schema/dataset

A comprehensive example including creator, temporal coverage, and distribution details.

```ts
defineDataset({
  name: 'Global Temperature Data 2000-2024',
  description: 'Daily temperature readings and anomaly calculations from weather stations worldwide',
  url: 'https://example.com/datasets/global-temp-2000-2024',
  creator: defineOrganization({
    name: 'Climate Research Institute',
    url: 'https://example.com/about',
  }),
  datePublished: new Date(2024, 0, 1),
  dateModified: new Date(2024, 11, 1),
  version: '2.0',
  keywords: ['climate', 'temperature', 'weather', 'global warming'],
  license: 'https://creativecommons.org/licenses/by/4.0/',
  temporalCoverage: '2000-01-01/2024-12-31',
  spatialCoverage: 'Global',
  distribution: {
    '@type': 'DataDownload',
    contentUrl: 'https://example.com/downloads/global-temp-data.csv',
    encodingFormat: 'CSV',
    contentSize: '125 MB',
  },
  variableMeasured: ['temperature', 'humidity', 'pressure'],
  citation: 'Smith, J. et al. (2024). Global Temperature Dataset. Climate Research Institute.',
  isAccessibleForFree: true,
})
```

--------------------------------

### Example URL transformation output

Source: https://unhead.unjs.io/docs/head/guides/plugins/canonical

Demonstrates how the customResolver transforms a relative path into an absolute URL.

```html
<meta property="og:image" content="/hero.jpg">
```

```html
<meta property="og:image" content="https://example.com/cdn/hero.jpg">
```

--------------------------------

### Define an Article node

Source: https://unhead.unjs.io/docs/angular/schema-org/api/composables/use-schema-org

Example of defining an Article schema node using the defineArticle helper.

```typescript
useSchemaOrg([
  defineArticle({
    headline: 'My Blog Post',
    image: '/images/post.jpg',
    datePublished: new Date(),
  })
])
```

--------------------------------

### Define Detailed Article

Source: https://unhead.unjs.io/docs/schema-org/api/schema/article

A comprehensive example including headline, description, images, dates, and author information.

```ts
defineArticle({
  headline: 'Article Title',
  description: 'Article description',
  image: '/articles/article-title-image.jpg',
  datePublished: new Date(2024, 0o5, 29),
  dateModified: new Date(2024, 0o5, 29),
  // attaching an author when the identity is an organization
  author: {
    name: 'Harlan Wilton',
    url: 'https://harlanzw.com',
  }
})
```

--------------------------------

### Initialize Client Streaming

Source: https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/streaming

Bootstrap the client-side head instance to process queued entries from the stream.

```ts
import { createStreamableHead } from 'unhead/stream/client'

const head = createStreamableHead()
if (!head)
  throw new Error('Unhead streaming bootstrap state is missing')
```

--------------------------------

### Define How-To Structured Data

Source: https://unhead.unjs.io/docs/schema-org/guides/recipes/how-to

Use defineHowTo to create a structured HowTo node, including detailed steps, materials, and tools.

```ts
import { defineHowTo, useSchemaOrg } from '@unhead/schema-org/@framework'

useSchemaOrg([
  defineHowTo({
    name: 'How to Build a Desk',
    description: 'A step-by-step guide to building a home office desk.',
    image: '/images/desk-building.jpg',
    estimatedCost: {
      '@type': 'MonetaryAmount',
      currency: 'USD',
      value: '100'
    },
    supply: [
      'Wood panels',
      'Screws',
      'Hammer',
      'Nails'
    ],
    tool: [
      'Screwdriver',
      'Power drill',
      'Tape measure'
    ],
    step: [
      {
        name: 'Gather materials',
        text: 'Collect all necessary supplies and tools.',
        image: '/images/desk-materials.jpg',
        url: '/how-to-build-desk/materials'
      },
      {
        name: 'Cut wood panels',
        text: 'Cut the wood panels to the proper dimensions.',
        image: '/images/cutting-panels.jpg',
        url: '/how-to-build-desk/cutting'
      },
      {
        name: 'Assemble desk frame',
        text: 'Connect the panels to form the desk frame.',
        image: '/images/desk-frame.jpg',
        url: '/how-to-build-desk/assembly'
      },
      {
        name: 'Attach desk top',
        text: 'Secure the desk top to the frame.',
        image: '/images/desk-top.jpg',
        url: '/how-to-build-desk/finishing'
      }
    ]
  })
])
```

--------------------------------

### Vue Head Provider Component

Source: https://unhead.unjs.io/docs/releases/v2

Example of using a HeadProvider component to collect metadata tags during rendering.

```vue
<HeadProvider>
  <title>My Page</title>
  <meta name="description" content="My page description" />
  <link rel="canonical" href="https://example.com/my-page" />
</HeadProvider>
```

--------------------------------

### Query Parameter Filtering Example

Source: https://unhead.unjs.io/docs/head/guides/plugins/canonical

Demonstration of how the plugin strips query parameters from canonical tags by default.

```html
<link rel="canonical" href="https://mysite.com/blog?page=2&utm_source=twitter&fbclid=abc">
```

```html
<link rel="canonical" href="https://mysite.com/blog">
```

--------------------------------

### Optimized Head Tag Ordering

Source: https://unhead.unjs.io

Example of the default head tag order optimized for SEO and performance.

```html
<head>  
  <script defer src="defer-script.js"></script>  
  <script src="sync-script.js"></script>  
  <style>.sync-style { color: red }</style>  
  <link rel="modulepreload" href="modulepreload.js">  
  <script src="async-script.js" async></script>  
  <link rel="preload" href="preload.js">  
  <link rel="stylesheet" href="sync-styles.css">  
  <title>title</title>  
  <link rel="preconnect" href="https://example.com">  
  <link rel="dns-prefetch" href="https://example.com">  
  <link rel="prefetch" href="https://example.com">  
  <link rel="prerender" href="https://example.com">  
  <meta name="description" content="description">  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">  
</head>
```

--------------------------------

### Initialize Schema.org with defineArticle

Source: https://unhead.unjs.io/docs/schema-org/guides/get-started/overview

Use the useSchemaOrg composable to register an Article node, which automatically resolves image paths and publication dates.

```ts
import { defineArticle, useSchemaOrg } from '@unhead/schema-org/@framework'

// Generates an Article node and resolves its image and publication date
useSchemaOrg([
  defineArticle({
    headline: 'My Blog Post',
    image: '/images/post.jpg',
    datePublished: new Date(),
  })
])
```

--------------------------------

### defineHowTo

Source: https://unhead.unjs.io/docs/schema-org/api/schema/how-to

The defineHowTo function is used to define the HowTo schema object. It accepts a configuration object containing the guide name and an array of steps.

```APIDOC
## defineHowTo

### Description
Defines a HowTo schema object for structured data. It maps guide metadata and steps to the Schema.org HowTo format.

### Parameters
- **name** (string) - Required - A string describing the guide.
- **step** (NodeRelations<HowToStep | string>[]) - Required - An array of objects or strings describing the steps in the guide.

### Step Object Properties
- **text** (string) - Required - The full instruction text for the step.
- **url** (string) - Optional - A URL associated with the step.
- **image** (string) - Optional - An image URL associated with the step.

### Example
```ts
defineHowTo({
  name: 'How to tie a tie',
  step: [
    {
      url: '#step-one',
      text: 'Button your shirt, then drape the tie around your neck.',
      image: '/1x1/photo.jpg',
    }
  ]
})
```

--------------------------------

### Using useScript with API Proxying

Source: https://unhead.unjs.io/docs/nuxt/head/api/composables/use-script

Demonstrates how to load an external script and interact with its API using a proxy that replays calls once the script resolves.

```typescript
import { useScript } from '#imports'

interface AnalyticsApi {
  track: (event: string) => void
}

const analytics = useScript<AnalyticsApi>('https://example.com/analytics.js', {
  use: () => window.analytics,
})

// Recorded now and replayed after the API resolves.
analytics.proxy.track('pageview')
```

--------------------------------

### Configure the Schema.org Plugin

Source: https://unhead.unjs.io/docs/solid-js/schema-org/guides/get-started/installation

Initialize the head instance with the UnheadSchemaOrg plugin, providing the required host parameter.

```tsx
import { UnheadSchemaOrg } from '@unhead/schema-org'
import { createHead, UnheadContext } from '@unhead/solid-js/client'
import { render } from 'solid-js/web'
import App from './App'

const head = createHead({
  plugins: [
    UnheadSchemaOrg({ host: 'https://example.com' }),
  ]
})

render(() => (
  <UnheadContext.Provider value={head}>
    <App />
  </UnheadContext.Provider>
), document.getElementById('root')!)
```

--------------------------------

### defineHeadPlugin

Source: https://unhead.unjs.io/docs/head/api/plugins

A type helper used to define plugin objects or setup functions that hook into the Unhead lifecycle.

```APIDOC
## defineHeadPlugin(plugin, key?)

### Description
Defines a plugin for Unhead. Plugins can be defined as objects with a `key` and `hooks`, or as setup functions that receive the `Unhead` instance.

### Parameters
- **plugin** (HeadPluginInput) - Required - An object containing a `key` and `hooks`, or a function returning such an object.
- **key** (string) - Optional - A static key used for deduplication when the plugin is a setup function.

### Usage Example
```ts
import { defineHeadPlugin } from 'unhead/plugins'

export const myPlugin = defineHeadPlugin({
  key: 'my-plugin',
  hooks: {
    'tags:resolve': (ctx) => {
      // Modify ctx.tags before rendering.
    },
  },
})
```
```

--------------------------------

### Handling untrusted data with useHeadSafe

Source: https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe

Example of using useHeadSafe to safely inject metadata fetched from an external source.

```typescript
import { useHeadSafe } from 'unhead'

const profile = await fetchUserProfile(userId)

useHeadSafe(unheadInstance, {
  title: profile.pageTitle,
  meta: [
    { name: 'description', content: profile.pageDescription },
    ...profile.customMetaTags,
  ],
})
```

--------------------------------

### Basic useSeoMeta() implementation

Source: https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta

Demonstrates the basic structure of passing a flat object of SEO metadata to the useSeoMeta composable.

```typescript
useSeoMeta(unheadInstance, {
  title: 'Page Title',
  description: 'Page description for search engines',
  ogTitle: 'Social Share Title',
  ogDescription: 'Description for social media',
  ogImage: 'https://example.com/og-image.jpg'
})
```

--------------------------------

### Applying Tag Priority

Source: https://unhead.unjs.io/docs/solid-js/head/api/composables/use-head

Example of applying a low priority to multiple meta tags using the options parameter.

```typescript
import { useHead } from '@unhead/solid-js'

useHead({
  meta: [
    { name: 'description', content: 'fallback description' },
    { name: 'author', content: 'fallback author' }
  ]
}, {
  tagPriority: 'low'
})
```

--------------------------------

### Configure Server-Side Rendering

Source: https://unhead.unjs.io/docs/angular/head/guides/get-started/installation

Register the server-side head provider with optional initial default values and bootstrap the server application.

```ts
import { ApplicationConfig, mergeApplicationConfig } from '@angular/core'
import { provideServerRendering } from '@angular/platform-server'
import { provideServerRoutesConfig } from '@angular/ssr'
import { provideServerHead } from '@unhead/angular/server'
import { appConfig } from './app.config'
import { serverRoutes } from './app.routes.server'

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(),
    provideServerRoutesConfig(serverRoutes),
    provideServerHead({
      // Optional initial default values
      init: [
        {
          htmlAttrs: {
            lang: 'en',
          },
          title: 'Default Title',
          meta: [
            { name: 'description', content: 'Default description' }
          ]
        }
      ]
    }),
  ]
}

export const config = mergeApplicationConfig(appConfig, serverConfig)
```

```ts
import { bootstrapApplication } from '@angular/platform-browser'
import { AppComponent } from './app/app.component'
import { config } from './app/app.config.server'

const bootstrap = () => bootstrapApplication(AppComponent, config)

export default bootstrap
```

--------------------------------

### Configure Client-Side Rendering

Source: https://unhead.unjs.io/docs/angular/head/guides/get-started/installation

Register the client-side head provider in the application configuration and bootstrap the application with it.

```ts
import { ApplicationConfig, mergeApplicationConfig } from '@angular/core'
import { provideClientHead } from '@unhead/angular/client'
import { appConfig } from './app.config'

const clientConfig: ApplicationConfig = {
  providers: [
    provideClientHead(),
  ]
}

export const config = mergeApplicationConfig(appConfig, clientConfig)
```

```ts
import { bootstrapApplication } from '@angular/platform-browser'
import { AppComponent } from './app/app.component'
import { config } from './app/app.config.client'

bootstrapApplication(AppComponent, config)
  .catch(err => console.error(err))
```

--------------------------------

### Detailed TV Series Definition

Source: https://unhead.unjs.io/docs/schema-org/api/schema/tv-series

A comprehensive example including cast, production details, ratings, and publication dates.

```ts
defineTVSeries({
  name: 'Breaking Bad',
  description: 'A chemistry teacher diagnosed with cancer turns to manufacturing meth',
  url: 'https://example.com/shows/breaking-bad',
  image: 'https://example.com/shows/breaking-bad-poster.jpg',
  numberOfSeasons: 5,
  numberOfEpisodes: 62,
  genre: ['Crime', 'Drama', 'Thriller'],
  actor: [
    { name: 'Bryan Cranston' },
    { name: 'Aaron Paul' },
  ],
  director: [
    { name: 'Vince Gilligan' },
  ],
  creator: {
    name: 'Vince Gilligan',
  },
  productionCompany: {
    name: 'AMC Studios',
  },
  datePublished: new Date(2008, 0, 20),
  aggregateRating: {
    ratingValue: 9.5,
    ratingCount: 1500000,
  },
})
```
Tokens:
Raw