/

The full stack <head> package for any framework.

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

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

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

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.

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

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

✅ 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")',
    }],
  })
}