/

The full stack <head> package for any framework.

Unhead wraps your document template, improving reactive SSR JavaScript framework SEO and performance.

Get Started Install Unhead

Unhead Principles

Why Unhead

Complete Developer Experience

useHead() with type narrowing, deduping, and tag merging
Flat useSeoMeta() for 100+ meta tags
useScript() for performant third party loading
useSchemaOrg() for automatic Schema.org graphs
Plugins for tag validation, canonical URLs, and 7 more

Built for Performance

~4.4kb gzipped, tree shakable utilities
Built in HTML minification
Streaming SSR with head tags pushed per chunk
Automatic Capo.js head tag ordering

Any Framework / Any Bundler

Vue, React, Solid.js, Svelte, and Angular
Vite, Webpack, Rollup, and more
Built in Vite Devtools integration
Hook into every stage of head resolution

Hello useHead()

Unhead aims to provide bullet-proof primitives for a minimal yet powerful API surface.

✅ Titles that just work

useHead({
  title: 'Hello World',
  titleTemplate: '%s %separator My App',
})
// Hello World - My App

✅ DOM Events

useHead({
  script: [{
    src: '/script.js',
    onload: () => alert('woo'),
  }],
})

✅ Classes and styles however you like

useHead({
  bodyAttrs: {
    // use strings
    style: 'background-color: #343434',
    // arrays
    class: ['dark', 'overflow'],
  },
  htmlAttrs: {
    // objects
    style: {
      backgroundColor: 'white',
      color: 'black',
    },
    // computed boolean objects
    class: {
      dark: () => Date.now() % 2 === 0,
    },
  },
})

Built For Reactive Lifecycles

All side effects are tracked so that unmounting a component will revert its head modifications and reactive updates can be made at any time.

useHead({
  title: 'Subscribe now!',
  htmlAttrs: {
    class: { dark: true, light: false }
  },
  bodyAttrs: {
    'style': { overflow: 'hidden' },
    'data-modal': true,
  },
  link: [{
    rel: 'preload',
    href: 'https://3p.com/subscribe.js',
    as: 'script',
  }],
})

Component Not Mounted

Optimized SEO Tags

Nail your SEO with foolproof flat meta config and the simplest Schema.org you've ever worked with.

Flat SEO Meta

Was it <meta property or <meta name? Who can remember, just use useSeoMeta().

useSeoMeta({
  ogType: 'article',
  author: 'Harlan Wilton',
  articleAuthor: ['Harlan Wilton'],
  articlePublishedTime: '2024-01-01',
  articleModifiedTime: '2024-01-01',
  twitterData1: 'Harlan Wilton',
  twitterLabel1: 'Author',
  twitterData2: '10 min',
  twitterLabel2: 'Read Time',
})

Schema.org Graphs

Rich result optimized Schema.org graphs without the application/ld+json.

useSchemaOrg([
  definePerson({
    name: 'Harlan Wilton',
    sameAs: [
      'https://github.com/harlan-zw',
    ],
    url: 'https://harlanzw.com',
  }),
  defineArticle({
    headline: 'Hello World',
    datePublished: '2024-01-01',
  }),
])

Making Websites Faster

Unhead ships to be tree shaken with client and server export paths.

Optimized Head tag ordering

Unhead ships with a default head tag order that is optimized for SEO and performance.

Enable Capo.js

A `<script>` for full stack javascript

Better developer experience, performance and privacy.

const script = useScript({
  src: 'https://js.cdn/tracker.js',
}, {
  trigger: useOnIdle()
})
script.onError((error) => { /* uh oh */ })
// proxy function calls for when the script is loaded
script.proxy.track('foo')
// or just use onLoaded
script.onLoaded((api) => {
  api.track('bar')
})

<link fetchpriority="low" as="script" crossorigin="anonymous" referrerpolicy="no-referrer" href="https://js.cdn/tracker.js" rel="preload">

<script data-onload data-onerror defer fetchpriority="low" crossorigin="anonymous" referrerpolicy="no-referrer" src="https://js.cdn/tracker.js">

✅ Optimized Client Bundles

// Unhead tags are built to tree-shake, it just works
if (import.meta.server) {
  useHead({
    meta: [{
      name: 'description',
      content: 'Hello World',
    }],
    script: [{
      innerHTML: 'console.log("Hello World")',
    }],
  })
}