0
# React Helmet
1

2
React Helmet is a document head manager for React applications that allows dynamic control of HTML head elements including title, meta tags, links, scripts, and other head content. It provides a declarative API through a Helmet component with nested component override capabilities and full server-side rendering support.
3

4
## Package Information
5

6
- **Package Name**: react-helmet
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install react-helmet`
10
- **Peer Dependencies**: React >=16.3.0
11

12
## Core Imports
13

14
```javascript
15
import { Helmet } from "react-helmet";
16
```
17

18
For default import:
19

20
```javascript
21
import Helmet from "react-helmet";
22
```
23

24
CommonJS:
25

26
```javascript
27
const { Helmet } = require("react-helmet");
28
```
29

30
## Basic Usage
31

32
```javascript
33
import React from "react";
34
import { Helmet } from "react-helmet";
35

36
function MyApp() {
37
  return (
38
    <div className="application">
39
      <Helmet>
40
        <meta charSet="utf-8" />
41
        <title>My Page Title</title>
42
        <meta name="description" content="My page description" />
43
        <link rel="canonical" href="https://mysite.com/example" />
44
      </Helmet>
45
      
46
      <h1>Page Content</h1>
47
    </div>
48
  );
49
}
50
```
51

52
## Architecture
53

54
React Helmet is built around several key components:
55

56
- **Declarative API**: Use standard HTML tags as children to manage head elements
57
- **Component Nesting**: Deeper nested components override parent head changes
58
- **Side Effect Management**: Uses react-side-effect to synchronize component state with DOM
59
- **Server Rendering**: Static methods extract head data for server-side rendering
60
- **Deduplication**: Automatically handles duplicate head elements with priority rules
61

62
## Capabilities
63

64
### Document Head Management
65

66
Core functionality for managing HTML head elements through declarative React components. Supports all valid head tags with automatic deduplication and nested component override behavior.
67

68
```javascript { .api }
69
function Helmet(props: HelmetProps): JSX.Element;
70

71
interface HelmetProps {
72
  /** Document title */
73
  title?: string;
74
  /** Fallback title when titleTemplate exists but no title is defined */
75
  defaultTitle?: string;
76
  /** Template for title with %s placeholder */
77
  titleTemplate?: string;
78
  /** Attributes for the title element */
79
  titleAttributes?: object;
80
  /** Attributes for the html element */
81
  htmlAttributes?: object;
82
  /** Attributes for the body element */
83
  bodyAttributes?: object;
84
  /** Array of meta tag objects */
85
  meta?: Array<object>;
86
  /** Array of link tag objects */
87
  link?: Array<object>;
88
  /** Array of script tag objects */
89
  script?: Array<object>;
90
  /** Array of style tag objects */
91
  style?: Array<object>;
92
  /** Array of noscript tag objects */
93
  noscript?: Array<object>;
94
  /** Base tag configuration */
95
  base?: object;
96
  /** Controls whether to use requestAnimationFrame for DOM updates (default: true) */
97
  defer?: boolean;
98
  /** Controls HTML entity encoding (server-side only) (default: true) */
99
  encodeSpecialCharacters?: boolean;
100
  /** Callback function that tracks DOM changes */
101
  onChangeClientState?: (newState: any, addedTags: any[], removedTags: any[]) => void;
102
  /** Child elements representing head tags */
103
  children?: React.ReactNode;
104
}
105
```
106

107
### Server-Side Rendering
108

109
Extract head data after server-side rendering for inclusion in HTML documents. Essential for SEO and prerendering scenarios.
110

111
```javascript { .api }
112
/** Extract head data after server-side rendering - must be called on server */
113
static renderStatic(): HelmetData;
114

115
/** Legacy alias for renderStatic() */
116
static rewind(): HelmetData;
117

118
/** Testing utility to get current state without resetting instance stack */
119
static peek(): HelmetData;
120

121
/** Controls DOM usage detection for server environments */
122
static set canUseDOM(value: boolean);
123

124
interface HelmetData {
125
  title: HelmetElement;
126
  base: HelmetElement;
127
  meta: HelmetElement;
128
  link: HelmetElement;
129
  script: HelmetElement;
130
  style: HelmetElement;
131
  noscript: HelmetElement;
132
  htmlAttributes: HelmetElement;
133
  bodyAttributes: HelmetElement;
134
}
135

136
interface HelmetElement {
137
  /** Convert to React components for JSX rendering */
138
  toComponent(): React.ReactElement[];
139
  /** Convert to HTML string for server-side rendering */
140
  toString(): string;
141
}
142
```
143

144
[Server-Side Rendering](./server-side-rendering.md)
145

146
## Supported Head Elements
147

148
React Helmet supports all valid HTML head elements:
149

150
### Title Management
151
```javascript { .api }
152
// Simple title
153
<title>Page Title</title>
154

155
// Title with attributes
156
<title itemProp="name" lang="en">Attributed Title</title>
157

158
// Title templating
159
<Helmet titleTemplate="MySite.com - %s">
160
  <title>Page Name</title>
161
</Helmet>
162
// Results in: "Page Name - MySite.com"
163
```
164

165
### Meta Tags
166
```javascript { .api }
167
<meta name="description" content="Page description" />
168
<meta property="og:type" content="article" />
169
<meta charSet="utf-8" />
170
<meta httpEquiv="X-UA-Compatible" content="IE=edge" />
171
```
172

173
### Link Elements
174
```javascript { .api }
175
<link rel="canonical" href="https://example.com/page" />
176
<link rel="stylesheet" href="/styles.css" />
177
<link rel="apple-touch-icon" sizes="180x180" href="/icon.png" />
178
```
179

180
### Script Elements
181
```javascript { .api }
182
// External scripts
183
<script src="https://example.com/script.js" type="text/javascript" />
184

185
// Inline scripts
186
<script type="application/ld+json">{`
187
  {
188
    "@context": "https://schema.org",
189
    "@type": "WebPage"
190
  }
191
`}</script>
192
```
193

194
### Style Elements
195
```javascript { .api }
196
<style type="text/css">{`
197
  body { background-color: blue; }
198
  .main { font-size: 16px; }
199
`}</style>
200
```
201

202
### Other Elements
203
```javascript { .api }
204
// Base element
205
<base target="_blank" href="https://example.com/" />
206

207
// Noscript fallbacks
208
<noscript>{`
209
  <link rel="stylesheet" type="text/css" href="fallback.css" />
210
`}</noscript>
211

212
// HTML and body attributes
213
<html lang="en" dir="ltr" />
214
<body className="app-root" data-theme="dark" />
215
```
216

217
## Component Behavior
218

219
### Nested Override Pattern
220

221
Deeper components override parent head changes, allowing flexible head management in component hierarchies:
222

223
```javascript
224
<App>
225
  <Helmet>
226
    <title>App Title</title>
227
    <meta name="description" content="App description" />
228
  </Helmet>
229
  
230
  <ProductPage>
231
    <Helmet>
232
      <title>Product Page</title>
233
      <meta name="description" content="Product description" />
234
    </Helmet>
235
  </ProductPage>
236
</App>
237

238
// Result: title="Product Page", description="Product description"
239
```
240

241
### Duplicate Handling
242

243
Multiple instances of the same tag type are preserved when specified in the same component, but deduplicated across components:
244

245
```javascript
246
// Same component - both icons preserved
247
<Helmet>
248
  <link rel="apple-touch-icon" sizes="57x57" href="/icon-57.png" />
249
  <link rel="apple-touch-icon" sizes="72x72" href="/icon-72.png" />
250
</Helmet>
251

252
// Different components - deeper component wins
253
<Parent>
254
  <Helmet>
255
    <link rel="canonical" href="https://example.com/parent" />
256
  </Helmet>
257
  <Child>
258
    <Helmet>
259
      <link rel="canonical" href="https://example.com/child" />
260
    </Helmet>
261
  </Child>
262
</Parent>
263
// Result: canonical = "https://example.com/child"
264
```