solidjs · everton-dgn · Dec 26, 2025 · Dec 26, 2025 · LadyBluenotes · Dec 28, 2025
diff --git a/src/routes/solid-meta/getting-started/installation-and-setup.mdx b/src/routes/solid-meta/getting-started/installation-and-setup.mdx
@@ -33,11 +33,12 @@ To get started, install using your preferred package manager.
 
 1. Wrap your application with [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider)
 2. To include head tags within your application, render any of the following:
-    1. [`<Title />`](/solid-meta/reference/meta/title): Adds the `title` of the page.
-    2. [`<Meta />`](/solid-meta/reference/meta/meta): Adds extra metadata to the page.
-    3. [`<Style />`](/solid-meta/reference/meta/style): Adds a `style` element to the page.
-    4. [`<Link />`](/solid-meta/reference/meta/link): Specifies a relationship between the page and an external resource.
-    5. [`<Base />`](/solid-meta/reference/meta/base): Specifies the base URL for all relative URLs in the document.
+	1. [`<Title />`](/solid-meta/reference/meta/title): Adds the `title` of the page.
+	2. [`<Meta />`](/solid-meta/reference/meta/meta): Adds extra metadata to the page.
+	3. [`<Style />`](/solid-meta/reference/meta/style): Adds a `style` element to the page.
+	4. [`<Link />`](/solid-meta/reference/meta/link): Specifies a relationship between the page and an external resource.
+	5. [`<Base />`](/solid-meta/reference/meta/base): Specifies the base URL for all relative URLs in the document.
+	6. [`useHead`](/solid-meta/reference/meta/use-head): Inserts arbitrary head tags when a dedicated component does not exist.
 - These components can be used multiple times within the application.
 3.  If using Solid on the server with JSX, no additional configuration is required.
 

diff --git a/src/routes/solid-meta/reference/meta/data.json b/src/routes/solid-meta/reference/meta/data.json
@@ -6,6 +6,7 @@
 		"meta.mdx",
 		"style.mdx",
 		"base.mdx",
-		"metaprovider.mdx"
+		"metaprovider.mdx",
+		"use-head.mdx"
 	]
 }
diff --git a/src/routes/solid-meta/reference/meta/use-head.mdx b/src/routes/solid-meta/reference/meta/use-head.mdx
@@ -0,0 +1,247 @@
+---
+title: useHead
+order: 7
+use_cases: >-
+  custom head tags, scripts, json-ld, arbitrary head elements, dynamic metadata,
+  ssr head management
+tags:
+  - usehead
+  - head
+  - meta
+  - script
+  - json-ld
+  - ssr
+version: '1.0'
+description: >-
+  useHead inserts custom elements into document head with fine-grained control,
+  including scripts and JSON-LD, while staying SSR-ready.
+---
+
+`useHead` registers a custom head tag with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider).
+It is the low-level API used by the head components.
+It must be called under a `MetaProvider`, or it throws.
+
+Use it when you need a tag that does not have a dedicated component or when you need full control over closing tags and escaping.
-`useHead` registers a custom head tag with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider).
-It is the low-level API used by the head components.
-It must be called under a `MetaProvider`, or it throws.
-
-Use it when you need a tag that does not have a dedicated component or when you need full control over closing tags and escaping.
+`useHead` is a low-level API for registering custom `<head>` tags with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider).
-`useHead` registers a custom head tag with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider).
-It is the low-level API used by the head components.
-It must be called under a `MetaProvider`, or it throws.
-
-Use it when you need a tag that does not have a dedicated component or when you need full control over closing tags and escaping.
+`useHead` is a low-level API for registering custom `<head>` tags with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider).
+
+## When to use useHead
+
+- Insert tags without built-in components, such as `script` and `noscript`.
+- Control SSR output with `setting.close` and `setting.escape`.
+- Inject per-page structured data like JSON-LD.
+- Reuse an existing element via `ref`.
+
+## Prefer components when possible
+
+Use the dedicated components when they fit your use case:
+
+- [`<Title />`](/solid-meta/reference/meta/title) for page titles.
+- [`<Meta />`](/solid-meta/reference/meta/meta) for metadata.
+- [`<Link />`](/solid-meta/reference/meta/link) for external resources.
+- [`<Style />`](/solid-meta/reference/meta/style) for inline styles.
+- [`<Base />`](/solid-meta/reference/meta/base) for base URLs.
+
+They provide clearer intent and sensible defaults.
+
+## Import
+
+```ts
+import { useHead } from "@solidjs/meta";
+```
+
+## Type
+
+```ts
+type TagDescription = {
+	tag: string;
+	props: Record<string, unknown>;
+	setting?: {
+		close?: boolean;
+		escape?: boolean;
+	};
+	id: string;
+	name?: string;
+	ref?: Element;
+};
+
+function useHead(tag: TagDescription): void;
+```
+
+## Parameters
+
+### `tag`
+
+- **Type:** `string`
+- **Required:** Yes
+
+The tag name to render in `<head>`, such as `script`, `meta`, or `title`.
-The tag name to render in `<head>`, such as `script`, `meta`, or `title`.
+The tag name to render in `<head>` (eg. `<script>`, `<meta>`, `<title>`).
-The tag name to render in `<head>`, such as `script`, `meta`, or `title`.
+The tag name to render in `<head>` (eg. `<script>`, `<meta>`, `<title>`).
+
+### `props`
+
+- **Type:** `Record<string, unknown>`
+- **Required:** Yes
+
+The attributes and properties applied to the element.
+
+#### `props.children`
+
+When provided, `children` becomes the element content for tags like `title`, `style`, or `script`.
+On the server, arrays of strings are concatenated without commas.
+If `setting.close` is not enabled, `children` is not rendered during SSR.
-### `props`
-
- **Type:** `Record<string, unknown>`
- **Required:** Yes
-
-The attributes and properties applied to the element.
-
-#### `props.children`
-
-When provided, `children` becomes the element content for tags like `title`, `style`, or `script`.
-On the server, arrays of strings are concatenated without commas.
-If `setting.close` is not enabled, `children` is not rendered during SSR.
+### `props`
+
+- **Type:** `Record<string, unknown>`
+- **Required:** Yes
+
+Attributes and properties applied to the rendered element.
+
+If `props.children` is provided, is provided, it is used as the element’s content for tags such as `title`, `style`, and `script`. 
+During server-side rendering, arrays of strings are concatenated without commas.
-### `props`
-
- **Type:** `Record<string, unknown>`
- **Required:** Yes
-
-The attributes and properties applied to the element.
-
-#### `props.children`
-
-When provided, `children` becomes the element content for tags like `title`, `style`, or `script`.
-On the server, arrays of strings are concatenated without commas.
-If `setting.close` is not enabled, `children` is not rendered during SSR.
+### `props`
+
+- **Type:** `Record<string, unknown>`
+- **Required:** Yes
+
+Attributes and properties applied to the rendered element.
+
+If `props.children` is provided, is provided, it is used as the element’s content for tags such as `title`, `style`, and `script`. 
+During server-side rendering, arrays of strings are concatenated without commas.
+
+### `setting`
+
+- **Type:** `{ close?: boolean; escape?: boolean }`
+- **Required:** No
+
+SSR-only rendering options for the tag contents.
+
+#### `setting.close`
+
+- **Type:** `boolean`
+- **Required:** No
+
+When `true`, the server renders a closing tag and includes `children`.
+Use this for tags that cannot be self-closing, such as `script`, `style`, and `title`.
-#### `setting.close`
-
- **Type:** `boolean`
- **Required:** No
-
-When `true`, the server renders a closing tag and includes `children`.
-Use this for tags that cannot be self-closing, such as `script`, `style`, and `title`.
+#### `close`
+
+- **Type:** `boolean`
+- **Required:** No
+
+Required for elements that cannot be self-closing, such as `script`, `style`, and `title`. When `true`, the server renders a closing tag and includes `children`. If `false`, `children` is not rendered.
-#### `setting.close`
-
- **Type:** `boolean`
- **Required:** No
-
-When `true`, the server renders a closing tag and includes `children`.
-Use this for tags that cannot be self-closing, such as `script`, `style`, and `title`.
+#### `close`
+
+- **Type:** `boolean`
+- **Required:** No
+
+Required for elements that cannot be self-closing, such as `script`, `style`, and `title`. When `true`, the server renders a closing tag and includes `children`. If `false`, `children` is not rendered.
+
+#### `setting.escape`
+
+- **Type:** `boolean`
+- **Required:** No
+
+When `true`, the server HTML-escapes `children`.
+If omitted or `false`, `children` is rendered as raw HTML.
-#### `setting.escape`
-
- **Type:** `boolean`
- **Required:** No
-
-When `true`, the server HTML-escapes `children`.
-If omitted or `false`, `children` is rendered as raw HTML.
+#### `escape`
+
+- **Type:** `boolean`
+- **Required:** No
+
+When `true`, HTML-escapes `children` during SSR.
+If omitted or `false`, renders `children` as raw HTML.
-#### `setting.escape`
-
- **Type:** `boolean`
- **Required:** No
-
-When `true`, the server HTML-escapes `children`.
-If omitted or `false`, `children` is rendered as raw HTML.
+#### `escape`
+
+- **Type:** `boolean`
+- **Required:** No
+
+When `true`, HTML-escapes `children` during SSR.
+If omitted or `false`, renders `children` as raw HTML.
+
+### `id`
+
+- **Type:** `string`
+- **Required:** Yes
+
+A stable identifier used to match server-rendered tags during hydration.
+Use a consistent `id` for the lifetime of the component.
-Use a consistent `id` for the lifetime of the component.
+Value should remain consistent for the lifetime of the component.
-Use a consistent `id` for the lifetime of the component.
+Value should remain consistent for the lifetime of the component.
+
+### `name`
+
+- **Type:** `string`
+- **Required:** No
+
+An optional label for the tag.
+For `meta` tags, it typically mirrors `props.name` or `props.property`.
-An optional label for the tag.
-For `meta` tags, it typically mirrors `props.name` or `props.property`.
+An optional label for the tag.
+With `meta` tags, can mirror `props.name` or `props.property`.
-An optional label for the tag.
-For `meta` tags, it typically mirrors `props.name` or `props.property`.
+An optional label for the tag.
+With `meta` tags, can mirror `props.name` or `props.property`.
+
+### `ref`
+
+- **Type:** `Element`
+- **Required:** No
+
+An existing element to reuse instead of creating a new one.
+This is usually managed internally.
-An existing element to reuse instead of creating a new one.
-This is usually managed internally.
+An existing element to reuse instead of creating a new one, typically managed internally.
-An existing element to reuse instead of creating a new one.
-This is usually managed internally.
+An existing element to reuse instead of creating a new one, typically managed internally.
+
+## Return value
+
+`useHead` does not return a value.
+
+## Usage
-## Usage
+## Examples
-## Usage
+## Examples
+
+### Simple custom tag
+
+```tsx
+import { useHead } from "@solidjs/meta";
+
+useHead({
+	tag: "link",
+	id: "rss-feed",
+	props: {
+		rel: "alternate",
+		type: "application/rss+xml",
+		title: "Solid RSS",
+		href: "/rss.xml",
+	},
+});
+```
+
+### JSON-LD per page (script with `close` and `escape`)
+
+```tsx
+import { useHead } from "@solidjs/meta";
+
+const jsonLD = JSON.stringify({
+	"@context": "https://schema.org",
+	"@type": "WebSite",
+	name: "Solid Docs",
+	url: "https://docs.solidjs.com/",
+});
+
+useHead({
+	tag: "script",
+	setting: { close: true, escape: false },
+	id: "schema-home",
+	props: {
+		type: "application/ld+json",
+		children: jsonLD,
+	},
+});
+```
+
+### Reactive updates
+
+```tsx
+import { createSignal } from "solid-js";
+import { useHead } from "@solidjs/meta";
+
+const [pageTitle, setPageTitle] = createSignal("Getting started");
+
+useHead({
+	tag: "title",
+	setting: { close: true, escape: true },
+	id: "page-title",
+	props: {
+		get children() {
+			return `${pageTitle()} | Solid`;
+		},
+	},
+});
+```
+
+## Notes
+
+### SSR and hydration
+
+On the server, tags are collected and rendered into `<head>`.
+During hydration, tags with matching `id` values are reused.
+On client-only renders, existing server tags are removed and replaced.
+
+### Dedupe and idempotency
+
+For `title` and `meta`, only the most recent tag with the same key is kept.
+The key is derived from the tag name and selected attributes.
+For `meta`, the key uses `name` (or `property`), `http-equiv`, `content`, `charset`, and `media`.
+For `title`, the key does not include any attributes.
+Other tag types are not deduped.
+The `id` does not control deduping.
+It ensures hydration can reuse the same element instead of inserting a duplicate.
+
+### Reactive updates and cleanup
+
+`useHead` runs inside a render effect.
+If your tag description reads reactive values, the tag updates when those values change.
+When the component unmounts, the tag is removed and any previous cascading tag is restored.
+
+### Security and escaping
+
+Use `setting.escape: true` when inserting untrusted content.
+Setting `escape: false` renders raw HTML and can create XSS risks.
+Only use `escape: false` with trusted, pre-serialized strings such as JSON-LD.
+
+### Best practices
+
+Use stable, unique `id` values to avoid duplicates.
+Prefer the dedicated head components when they meet your needs.
+Avoid inserting multiple tags that represent the same metadata unless you intend to override.
+
+## Related
+
+- [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider)
+- [`<Title />`](/solid-meta/reference/meta/title)
+- [`<Meta />`](/solid-meta/reference/meta/meta)
+- [`<Link />`](/solid-meta/reference/meta/link)
+- [`<Style />`](/solid-meta/reference/meta/style)
+- [`<Base />`](/solid-meta/reference/meta/base)