Skip to content

Commit c9801a1

Browse files
everton-dgnLadyBluenoteskodiakhq[bot]
authored
docs(solid-meta): add useHead reference (#1387)
Co-authored-by: Sarah <[email protected]> Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
1 parent 4d0357e commit c9801a1

File tree

3 files changed

+191
-6
lines changed

3 files changed

+191
-6
lines changed

‎src/routes/solid-meta/getting-started/installation-and-setup.mdx‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,12 @@ To get started, install using your preferred package manager.
3333

3434
1. Wrap your application with [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider)
3535
2. To include head tags within your application, render any of the following:
36-
1. [`<Title />`](/solid-meta/reference/meta/title): Adds the `title` of the page.
37-
2. [`<Meta />`](/solid-meta/reference/meta/meta): Adds extra metadata to the page.
38-
3. [`<Style />`](/solid-meta/reference/meta/style): Adds a `style` element to the page.
39-
4. [`<Link />`](/solid-meta/reference/meta/link): Specifies a relationship between the page and an external resource.
40-
5. [`<Base />`](/solid-meta/reference/meta/base): Specifies the base URL for all relative URLs in the document.
36+
1. [`<Title />`](/solid-meta/reference/meta/title): Adds the `title` of the page.
37+
2. [`<Meta />`](/solid-meta/reference/meta/meta): Adds extra metadata to the page.
38+
3. [`<Style />`](/solid-meta/reference/meta/style): Adds a `style` element to the page.
39+
4. [`<Link />`](/solid-meta/reference/meta/link): Specifies a relationship between the page and an external resource.
40+
5. [`<Base />`](/solid-meta/reference/meta/base): Specifies the base URL for all relative URLs in the document.
41+
6. [`useHead`](/solid-meta/reference/meta/use-head): Inserts arbitrary head tags when a dedicated component does not exist.
4142
- These components can be used multiple times within the application.
4243
3. If using Solid on the server with JSX, no additional configuration is required.
4344

‎src/routes/solid-meta/reference/meta/data.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"meta.mdx",
77
"style.mdx",
88
"base.mdx",
9-
"metaprovider.mdx"
9+
"metaprovider.mdx",
10+
"use-head.mdx"
1011
]
1112
}

‎src/routes/solid-meta/reference/meta/use-head.mdx‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: useHead
3+
order: 7
4+
use_cases: >-
5+
custom head tags, scripts, json-ld, arbitrary head elements, dynamic metadata,
6+
ssr head management
7+
tags:
8+
- usehead
9+
- head
10+
- meta
11+
- script
12+
- json-ld
13+
- ssr
14+
version: '1.0'
15+
description: >-
16+
useHead inserts custom elements into document head with fine-grained control,
17+
including scripts and JSON-LD, while staying SSR-ready.
18+
---
19+
20+
`useHead` is a low-level API for registering custom `<head>` tags with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider).
21+
22+
## Import
23+
24+
```ts
25+
import { useHead } from "@solidjs/meta";
26+
```
27+
28+
## Type
29+
30+
```ts
31+
type TagDescription = {
32+
tag: string;
33+
props: Record<string, unknown>;
34+
setting?: {
35+
close?: boolean;
36+
escape?: boolean;
37+
};
38+
id: string;
39+
name?: string;
40+
ref?: Element;
41+
};
42+
43+
function useHead(tag: TagDescription): void;
44+
```
45+
46+
## Parameters
47+
48+
### `tag`
49+
50+
- **Type:** `string`
51+
- **Required:** Yes
52+
53+
The tag name to render in `<head>` (eg. `<script>`, `<meta>`, `<title>`).
54+
55+
### `props`
56+
57+
- **Type:** `Record<string, unknown>`
58+
- **Required:** Yes
59+
60+
Attributes and properties applied to the rendered element.
61+
62+
If `props.children` is provided, is provided, it is used as the element’s content for tags such as `title`, `style`, and `script`.
63+
During server-side rendering, arrays of strings are concatenated without commas.
64+
65+
### `setting`
66+
67+
- **Type:** `{ close?: boolean; escape?: boolean }`
68+
- **Required:** No
69+
70+
SSR-only rendering options for the tag contents.
71+
72+
#### `close`
73+
74+
- **Type:** `boolean`
75+
- **Required:** No
76+
77+
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.
78+
79+
#### `escape`
80+
81+
- **Type:** `boolean`
82+
- **Required:** No
83+
84+
When `true`, HTML-escapes `children` during SSR.
85+
If omitted or `false`, renders `children` as raw HTML.
86+
87+
### `id`
88+
89+
- **Type:** `string`
90+
- **Required:** Yes
91+
92+
A stable identifier used to match server-rendered tags during hydration.
93+
Value should remain consistent for the lifetime of the component.
94+
95+
### `name`
96+
97+
- **Type:** `string`
98+
- **Required:** No
99+
100+
An optional label for the tag.
101+
With `meta` tags, can mirror `props.name` or `props.property`.
102+
103+
### `ref`
104+
105+
- **Type:** `Element`
106+
- **Required:** No
107+
108+
An existing element to reuse instead of creating a new one, typically managed internally.
109+
110+
## Return value
111+
112+
`useHead` does not return a value.
113+
114+
## Examples
115+
116+
### Simple custom tag
117+
118+
```tsx
119+
import { useHead } from "@solidjs/meta";
120+
121+
useHead({
122+
tag: "link",
123+
id: "rss-feed",
124+
props: {
125+
rel: "alternate",
126+
type: "application/rss+xml",
127+
title: "Solid RSS",
128+
href: "/rss.xml",
129+
},
130+
});
131+
```
132+
133+
### JSON-LD per page (script with `close` and `escape`)
134+
135+
```tsx
136+
import { useHead } from "@solidjs/meta";
137+
138+
const jsonLD = JSON.stringify({
139+
"@context": "https://schema.org",
140+
"@type": "WebSite",
141+
name: "Solid Docs",
142+
url: "https://docs.solidjs.com/",
143+
});
144+
145+
useHead({
146+
tag: "script",
147+
setting: { close: true, escape: false },
148+
id: "schema-home",
149+
props: {
150+
type: "application/ld+json",
151+
children: jsonLD,
152+
},
153+
});
154+
```
155+
156+
### Reactive updates
157+
158+
```tsx
159+
import { createSignal } from "solid-js";
160+
import { useHead } from "@solidjs/meta";
161+
162+
const [pageTitle, setPageTitle] = createSignal("Getting started");
163+
164+
useHead({
165+
tag: "title",
166+
setting: { close: true, escape: true },
167+
id: "page-title",
168+
props: {
169+
get children() {
170+
return `${pageTitle()} | Solid`;
171+
},
172+
},
173+
});
174+
```
175+
176+
## Related
177+
178+
- [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider)
179+
- [`<Title />`](/solid-meta/reference/meta/title)
180+
- [`<Meta />`](/solid-meta/reference/meta/meta)
181+
- [`<Link />`](/solid-meta/reference/meta/link)
182+
- [`<Style />`](/solid-meta/reference/meta/style)
183+
- [`<Base />`](/solid-meta/reference/meta/base)

0 commit comments

Comments
 (0)