useHead

useHead(input) declares a component's contribution to <head>: the title, <meta>, <link>, <script> and <style> tags, and <html> and <body> attributes. Meeko combines entries from document in meeko.config.ts, app/app.meeko, layouts, the page and its components, and the route's head under one priority rule, and removes a component's entries when it unmounts.

On the server it writes them to HTML; in the browser, hydration adopts those same tags without duplicating them, and a getter or signal updates the document on change. It is auto-imported in applications.

Usage#

<!-- app/pages/inbox.meeko -->
<script lang="ts">
const unread = signal(3);
useHead(() => ({
  title: unread.value ? `(${unread.value}) Inbox` : "Inbox",
  meta: [{ name: "robots", content: "noindex" }],
}));
</script>

<template><button on:click="() => unread.value = 0">Mark as read</button></template>

Clicking the button changes the document title without reloading.

Type#

function useHead(input: HeadSource<HeadInput>): void

interface HeadInput {
	title?: string
	titleTemplate?: string | ((title: string) => string)
	meta?: HeadMeta[]
	link?: HeadLink[]
	script?: HeadScript[]
	style?: HeadStyle[]
	htmlAttrs?: Record<string, string | undefined> & HeadEventAttributes
	bodyAttrs?: Record<string, string | undefined> & HeadEventAttributes
}

Parameters#

HeadInput accepts:

Return value#

void. Outside a Meeko application (for example, in a unit test with renderToString), it does nothing.

Examples#

A reactive title from page data#

<!-- app/pages/products/[id].meeko -->
<script server lang="ts">
const { params } = usePage();
export const product = await findProduct(params.id);
</script>

<script lang="ts">
const quantity = signal(1);
useHead(() => ({ title: `${product.name} (${quantity.value})` }));
</script>

Structured data for search engines#

An inline application/ld+json script; Meeko escapes every < so content cannot close the tag:

<script lang="ts">
const props = defineProps<{ data: { title: string; author: string; publishedAt: string } }>();
useHead(() => ({
  script: [{
    type: "application/ld+json",
    children: JSON.stringify({ "@context": "https://schema.org", "@type": "Article", headline: props.data.title, author: props.data.author, datePublished: props.data.publishedAt }),
  }],
}));
</script>

<html> and <body> attributes from a layout#

<!-- app/layouts/docs.meeko -->
<script lang="ts">
const sidebarOpen = signal(false);
useHead(() => ({
  htmlAttrs: { lang: "es", class: "docs" },
  bodyAttrs: { "data-sidebar": sidebarOpen.value ? "open" : undefined },
}));
</script>

<template><main><MeekoOutlet /></main></template>

A reusable head composable#

useHead can be called inside a composable invoked by the script:

// app/composables/useNoIndex.ts
import { useHead } from "@meekojs/meeko/framework";

export function useNoIndex(): void {
  useHead({ meta: [{ name: "robots", content: "noindex, nofollow", key: "robots" }] });
}

In <script server>#

In top-level server block code, useHead becomes part of the route's head, the highest-priority entry:

<script server lang="ts">
const { params } = usePage();
const post = await posts.find(params.slug);
useHead({ title: post.title, link: [{ rel: "canonical", href: `https://example.com/blog/${post.slug}` }] });
export const body = post.html;
</script>

Common mistakes#

An object that reads signals only once#

const count = signal(0);
useHead({ title: `${count.value} elementos` });

meeko check accepts this, but the title is calculated once when the script runs: changing count does not update it. Pass a getter so the title tracks the signal:

useHead(() => ({ title: `${count.value} elementos` }));

A meta tag without content#

useHead({ meta: [{ name: "description" }] });

meeko check reports TS2741: Property 'content' is missing in type '{ name: string; }' but required in type 'HeadMeta'. A description is shorter with useSeoMeta:

useHead({ meta: [{ name: "description", content: "Plans and pricing" }] });

Event handlers in attributes#

useHead({ bodyAttrs: { onload: "init()" } });

Since 1.7, meeko check reports TS2322: Type 'string' is not assignable to type 'never'. for DOM event handlers (onload, onclick…). Any other on* attribute (onLoad, onmievento) passes types, but Meeko rejects it at runtime: TypeError: useHead.bodyAttrs: event handler attribute onLoad is not allowed. Put code in the component script:

onMounted(() => init());

A function in configuration's titleTemplate#

document in meeko.config.ts is fixed as JSON during the build.

export default defineMeekoConfig({ document: { head: { titleTemplate: (title) => `${title} · Mi sitio` } } });

meeko check reports TS2322: Type '(title: string) => string' is not assignable to type 'string' in meeko.config.ts, because DocumentHead only accepts a string. Use %s, or put the function in a useHead in app/app.meeko:

export default defineMeekoConfig({ document: { head: { titleTemplate: "%s · Mi sitio" } } });

Notes#

• Priority. Lowest to highest: configuration's document, app/app.meeko, each layout (innermost wins), the page with its components and the route's head (export const head, route.head or useHead in <script server>). Within one level, the later call wins. <html> and <body> attributes merge by name with the same priority.
• Deduplication. Each tag has a key: explicit key or its natural key (name, property or httpEquiv in meta, with its media; rel and href in link, except canonical and icon, which are unique; src or code in script; CSS in style). For the same key, only the highest-priority entry remains.
• SSR. Managed tags go in <head> between <!--meeko:head--> and <!--/meeko:head-->, with escaped attributes and the request's CSP nonce on <script> and <style>.
• Navigation. On navigation, unmounted components' entries disappear and what they replaced returns; going back restores the page's entries. A changed script becomes a new element, executed by the browser.
• Security. Inline script and style content is not escaped as HTML: do not put unvalidated user text there. Attribute values are escaped.
• Dry run. In a client navigation's preliminary render, useHead does nothing; the committed render applies it.

Related#

• useSeoMetaTyped useHead shortcut for SEO that converts each field (description, Open Graph, Twitter, canonical) to the correct tag.
• definePageDeclares a page's route options (params and search schemas, rendering mode, loader, head, layout, middleware, cache and sitemap) with types flowing between them.
• <script server>A page's server code inside its .meeko file, with route options and typed JSON data exported to the template.
• documentThe application's shared HTML document, with html lang, head tags for all pages, per-page canonical and Open Graph tags and the useId prefix.
• Document head: document, useHead and useSeoMetaMeeko as a full-stack framework
• Per-page canonical URL and Open GraphMeeko as a full-stack framework