Unhead

Introduction

Unhead has first-class support for Solid.js, allowing you to manage your head tags using the useHead() hook, and other ecosystem hooks.

It can directly replace Solid-Meta, handling a more diverse set of use cases from SEO to structured data.

It's designed to work with any Solid.js setup, however this guide assumes you're following a similar structure to the Vite: ssr-solid-js-ts template or a similar SPA setup.

Demos

Setup

1. Add Dependency

Install @unhead/solid-js dependency to your project. The next tag is for v2 of Unhead which is required for Solid.js.

bash
pnpm add @unhead/solid-js@next

2. Setup Client-Side Rendering

To begin with, we'll import the function to initialize Unhead in our client Solid.js app from @unhead/solid-js/client.

In Vite this entry file is typically named entry-client.ts. If you're not server-side rendering, you can add this to your main Solid.js app entry instead.

src/entry-client.ts
import { createHead, UnheadContext } from '@unhead/solid-js/client'
import { hydrate } from 'solid-js/web'
import App from './App'
/* @refresh reload */
import './index.css'

hydrate(() => {
  const head = createHead()
  return (<UnheadContext.Provider value={head}><App /></UnheadContext.Provider>)
}, document.getElementById('root'))

3. Setup Server-Side Rendering

Serving your app as an SPA? You can skip this step.

Setting up server-side rendering is more complicated as it requires rendering out the tags to the HTML string before sending it to the client.

We'll start with setting up the plugin in the server entry this time. Make sure to import from @unhead/solid-js/server instead and add the head in the return object.

src/entry-server.ts
import { createHead, UnheadContext } from '@unhead/solid-js/server'
import { renderToString } from 'solid-js/web'
import App from './App'

export function render(_url: string) {
  const unhead = createHead()
  const html = renderToString(() => <UnheadContext.Provider value={unhead}><App /></UnheadContext.Provider>)
  return { html, unhead }
}

Now we need to render out the head tags after Solid.js has rendered the app.

Within your server.js file or wherever you're handling the template logic, you need to transform the template data for the head tags using transformHtmlTemplate().

server.ts
import { transformHtmlTemplate } from '@unhead/solid-js/server'
// ...

// Serve HTML
app.use('*all', async (req, res) => {
  try {
    // ...

    const rendered = await render(url)

    const html = await transformHtmlTemplate(
      rendered.unhead,
      template
        .replace(`<!--app-head-->`, generateHydrationScript())
        .replace(`<!--app-html-->`, rendered.html ?? '')
    )

    res.status(200).set({ 'Content-Type': 'text/html' }).send(html)
  }
  catch (e) {
    // ...
  }
})
// ..

4. Your First Tags

Done! Your app should now be rendering head tags on the server and client.

To improve your apps stability, Unhead will now insert important default tags for you.

  • <meta charset="utf-8">
  • <meta name="viewport" content="width=device-width, initial-scale=1">
  • <html lang="en">

You may need to change these for your app requirements, for example you may want to change the default language. Adding tags in your server entry means you won't add any weight to your client bundle.

src/entry-server.ts
import { createHead, UnheadContext } from '@unhead/solid-js/server'
import { renderToString } from 'solid-js/web'
import App from './App'

export function render(_url: string) {
  const unhead = createHead({
    // change default initial lang
    init: [
      {
        htmlAttrs: { lang: 'en' },
        title: 'Default title',
        titleTemplate: '%s - My Site',
      },
    ]
  })
  const html = renderToString(() => <UnheadContext.Provider value={unhead}><App /></UnheadContext.Provider>)
  return { html, unhead }
}

For adding tags in your components, you can either use the useHead() hook.

App.tsx
import { Head, useHead } from '@unhead/solid-js'

export default function App() {
  // a. use the hook
  useHead({
    title: 'My Awesome Site',
    meta: [
      { name: 'description', content: 'My awesome site description' }
    ]
  })
  // b. use the component
  return (
    <div>
      <Head>
        <title>My Awesome Site</title>
        <meta name="description" content="My awesome site description" />
      </Head>
      <h1>Hello World</h1>
    </div>
  )
}

5. Optional: Auto-Imports

If you're using unplugin-auto-import, you can automatically import the composables.

vite.config.ts
import { hookImports } from '@unhead/solid-js'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    AutoImport({
      imports: [
        hookImports,
      ],
    }),
    // ...
  ]
})

Next Steps

Your Solid.js app is now setup for head management, congrats! 🎉

You can get started with any of the hooks or components:

Or explore some of the optional extras:

Did this page help you?

Migrate from React Helmet

A practical guide to replace React Helmet with Unhead in your React applications.

Reactivity

Learn how to handle state changes for head tags in React - from basic state updates to complex data flows.