{
  "id": "ef8a46e17774e5ebf8d0aaa2",
  "source": "solid:signals",
  "type": "github-document",
  "title": "use-head",
  "content": "---\ntitle: useHead\norder: 7\nuse_cases: \u003e-\n  custom head tags, scripts, json-ld, arbitrary head elements, dynamic metadata,\n  ssr head management\ntags:\n  - usehead\n  - head\n  - meta\n  - script\n  - json-ld\n  - ssr\nversion: '1.0'\ndescription: \u003e-\n  useHead inserts custom elements into document head with fine-grained control,\n  including scripts and JSON-LD, while staying SSR-ready.\n---\n\n`useHead` is a low-level API for registering custom `\u003chead\u003e` tags with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider).\n\n## Import\n\n```ts\nimport { useHead } from \"@solidjs/meta\";\n```\n\n## Type\n\n```ts\ntype TagDescription = {\n\ttag: string;\n\tprops: Record\u003cstring, unknown\u003e;\n\tsetting?: {\n\t\tclose?: boolean;\n\t\tescape?: boolean;\n\t};\n\tid: string;\n\tname?: string;\n\tref?: Element;\n};\n\nfunction useHead(tag: TagDescription): void;\n```\n\n## Parameters\n\n### `tag`\n\n- **Type:** `string`\n- **Required:** Yes\n\nThe tag name to render in `\u003chead\u003e` (eg. `\u003cscript\u003e`, `\u003cmeta\u003e`, `\u003ctitle\u003e`).\n\n### `props`\n\n- **Type:** `Record\u003cstring, unknown\u003e`\n- **Required:** Yes\n\nAttributes and properties applied to the rendered element.\n\nIf `props.children` is provided, is provided, it is used as the element’s content for tags such as `title`, `style`, and `script`.\nDuring server-side rendering, arrays of strings are concatenated without commas.\n\n### `setting`\n\n- **Type:** `{ close?: boolean; escape?: boolean }`\n- **Required:** No\n\nSSR-only rendering options for the tag contents.\n\n#### `close`\n\n- **Type:** `boolean`\n- **Required:** No\n\nRequired 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.\n\n#### `escape`\n\n- **Type:** `boolean`\n- **Required:** No\n\nWhen `true`, HTML-escapes `children` during SSR.\nIf omitted or `false`, renders `children` as raw HTML.\n\n### `id`\n\n- **Type:** `string`\n- **Required:** Yes\n\nA stable identifier used to match server-rendered tags during hydration.\nValue should remain consistent for the lifetime of the component.\n\n### `name`\n\n- **Type:** `string`\n- **Required:** No\n\nAn optional label for the tag.\nWith `meta` tags, can mirror `props.name` or `props.property`.\n\n### `ref`\n\n- **Type:** `Element`\n- **Required:** No\n\nAn existing element to reuse instead of creating a new one, typically managed internally.\n\n## Return value\n\n`useHead` does not return a value.\n\n## Examples\n\n### Simple custom tag\n\n```tsx\nimport { useHead } from \"@solidjs/meta\";\n\nuseHead({\n\ttag: \"link\",\n\tid: \"rss-feed\",\n\tprops: {\n\t\trel: \"alternate\",\n\t\ttype: \"application/rss+xml\",\n\t\ttitle: \"Solid RSS\",\n\t\thref: \"/rss.xml\",\n\t},\n});\n```\n\n### JSON-LD per page (script with `close` and `escape`)\n\n```tsx\nimport { useHead } from \"@solidjs/meta\";\n\nconst jsonLD = JSON.stringify({\n\t\"@context\": \"https://schema.org\",\n\t\"@type\": \"WebSite\",\n\tname: \"Solid Docs\",\n\turl: \"https://docs.solidjs.com/\",\n});\n\nuseHead({\n\ttag: \"script\",\n\tsetting: { close: true, escape: false },\n\tid: \"schema-home\",\n\tprops: {\n\t\ttype: \"application/ld+json\",\n\t\tchildren: jsonLD,\n\t},\n});\n```\n\n### Reactive updates\n\n```tsx\nimport { createSignal } from \"solid-js\";\nimport { useHead } from \"@solidjs/meta\";\n\nconst [pageTitle, setPageTitle] = createSignal(\"Getting started\");\n\nuseHead({\n\ttag: \"title\",\n\tsetting: { close: true, escape: true },\n\tid: \"page-title\",\n\tprops: {\n\t\tget children() {\n\t\t\treturn `${pageTitle()} | Solid`;\n\t\t},\n\t},\n});\n```\n\n## Related\n\n- [`\u003cMetaProvider /\u003e`](/solid-meta/reference/meta/metaprovider)\n- [`\u003cTitle /\u003e`](/solid-meta/reference/meta/title)\n- [`\u003cMeta /\u003e`](/solid-meta/reference/meta/meta)\n- [`\u003cLink /\u003e`](/solid-meta/reference/meta/link)\n- [`\u003cStyle /\u003e`](/solid-meta/reference/meta/style)\n- [`\u003cBase /\u003e`](/solid-meta/reference/meta/base)",
  "url": "https://github.com/solidjs/solid-docs/blob/HEAD/src/routes/solid-meta/reference/meta/use-head.mdx",
  "metadata": {
    "path": "src/routes/solid-meta/reference/meta/use-head.mdx",
    "repo": "solidjs/solid-docs",
    "repo_url": "https://github.com/solidjs/solid-docs.git",
    "size": 3746,
    "source_type": "github"
  },
  "hash": "1a6b1c21cde864b56db243b1a1c0829a18475d98365f2511f91f0c4ac0dd762e",
  "timestamp": "2026-02-23T11:43:00.191388102+01:00"
}