diff --git a/src/routes/solid-meta/getting-started/installation-and-setup.mdx b/src/routes/solid-meta/getting-started/installation-and-setup.mdx index 304c6af61c..69606c0316 100644 --- 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 [``](/solid-meta/reference/meta/metaprovider) 2. To include head tags within your application, render any of the following: - 1. [``](/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 index 640bff60cb..56a76d69dc 100644 --- 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 new file mode 100644 index 0000000000..2b611a4f39 --- /dev/null +++ b/src/routes/solid-meta/reference/meta/use-head.mdx @@ -0,0 +1,183 @@ +--- +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` is a low-level API for registering custom `<head>` tags with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider). + +## 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>` (eg. `<script>`, `<meta>`, `<title>`). + +### `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. + +#### `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. + +#### `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. +Value should remain consistent for the lifetime of the component. + +### `name` + +- **Type:** `string` +- **Required:** No + +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, typically managed internally. + +## Return value + +`useHead` does not return a value. + +## 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`; + }, + }, +}); +``` + +## 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)