UNPKG

7.95 kBMarkdownView Raw
1<img align="right" width="200" src="http://static.nfl.com/static/content/public/static/img/logos/react-helmet.jpg" />
2
3# React Helmet
4
5[![npm Version](https://img.shields.io/npm/v/react-helmet.svg?style=flat-square)](https://www.npmjs.org/package/react-helmet)
6[![codecov.io](https://img.shields.io/codecov/c/github/nfl/react-helmet.svg?branch=master&style=flat-square)](https://codecov.io/github/nfl/react-helmet?branch=master)
7[![Build Status](https://img.shields.io/travis/nfl/react-helmet/master.svg?style=flat-square)](https://travis-ci.org/nfl/react-helmet)
8[![Dependency Status](https://img.shields.io/david/nfl/react-helmet.svg?style=flat-square)](https://david-dm.org/nfl/react-helmet)
9[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md#pull-requests)
10
11This reusable React component will manage all of your changes to the document head.
12
13Helmet _takes_ plain HTML tags and _outputs_ plain HTML tags. It's dead simple, and React beginner friendly.
14
15## [6.0.0 Breaking Changes](https://github.com/nfl/react-helmet/releases/tag/6.0.0)
16
17
18## Example
19```javascript
20import React from "react";
21import {Helmet} from "react-helmet";
22
23class Application extends React.Component {
24 render () {
25 return (
26 <div className="application">
27 <Helmet>
28 <meta charSet="utf-8" />
29 <title>My Title</title>
30 <link rel="canonical" href="http://mysite.com/example" />
31 </Helmet>
32 ...
33 </div>
34 );
35 }
36};
37```
38
39Nested or latter components will override duplicate changes:
40
41```javascript
42<Parent>
43 <Helmet>
44 <title>My Title</title>
45 <meta name="description" content="Helmet application" />
46 </Helmet>
47
48 <Child>
49 <Helmet>
50 <title>Nested Title</title>
51 <meta name="description" content="Nested component" />
52 </Helmet>
53 </Child>
54</Parent>
55```
56
57outputs:
58
59```html
60<head>
61 <title>Nested Title</title>
62 <meta name="description" content="Nested component">
63</head>
64```
65
66See below for a full reference guide.
67
68## Features
69- Supports all valid head tags: `title`, `base`, `meta`, `link`, `script`, `noscript`, and `style` tags.
70- Supports attributes for `body`, `html` and `title` tags.
71- Supports server-side rendering.
72- Nested components override duplicate head changes.
73- Duplicate head changes are preserved when specified in the same component (support for tags like "apple-touch-icon").
74- Callback for tracking DOM changes.
75
76## Compatibility
77
78Helmet 5 is fully backward-compatible with previous Helmet releases, so you can upgrade at any time without fear of breaking changes. We encourage you to update your code to our more semantic API, but please feel free to do so at your own pace.
79
80## Installation
81
82Yarn:
83```bash
84yarn add react-helmet
85```
86
87npm:
88```bash
89npm install --save react-helmet
90```
91
92## Server Usage
93To use on the server, call `Helmet.renderStatic()` after `ReactDOMServer.renderToString` or `ReactDOMServer.renderToStaticMarkup` to get the head data for use in your prerender.
94
95Because this component keeps track of mounted instances, **you have to make sure to call `renderStatic` on server**, or you'll get a memory leak.
96
97```javascript
98ReactDOMServer.renderToString(<Handler />);
99const helmet = Helmet.renderStatic();
100```
101
102This `helmet` instance contains the following properties:
103- `base`
104- `bodyAttributes`
105- `htmlAttributes`
106- `link`
107- `meta`
108- `noscript`
109- `script`
110- `style`
111- `title`
112
113Each property contains `toComponent()` and `toString()` methods. Use whichever is appropriate for your environment. For attributes, use the JSX spread operator on the object returned by `toComponent()`. E.g:
114
115### As string output
116```javascript
117const html = `
118 <!doctype html>
119 <html ${helmet.htmlAttributes.toString()}>
120 <head>
121 ${helmet.title.toString()}
122 ${helmet.meta.toString()}
123 ${helmet.link.toString()}
124 </head>
125 <body ${helmet.bodyAttributes.toString()}>
126 <div id="content">
127 // React stuff here
128 </div>
129 </body>
130 </html>
131`;
132```
133
134### As React components
135```javascript
136function HTML () {
137 const htmlAttrs = helmet.htmlAttributes.toComponent();
138 const bodyAttrs = helmet.bodyAttributes.toComponent();
139
140 return (
141 <html {...htmlAttrs}>
142 <head>
143 {helmet.title.toComponent()}
144 {helmet.meta.toComponent()}
145 {helmet.link.toComponent()}
146 </head>
147 <body {...bodyAttrs}>
148 <div id="content">
149 // React stuff here
150 </div>
151 </body>
152 </html>
153 );
154}
155```
156
157### Note: Use the same instance
158If you are using a prebuilt compilation of your app with webpack in the server be sure to include this in the `webpack file` so that the same instance of `react-helmet` is used.
159```
160externals: ["react-helmet"],
161```
162Or to import the *react-helmet* instance from the app on the server.
163
164### Reference Guide
165
166```javascript
167<Helmet
168 {/* (optional) set to false to disable string encoding (server-only) */}
169 encodeSpecialCharacters={true}
170
171 {/*
172 (optional) Useful when you want titles to inherit from a template:
173
174 <Helmet
175 titleTemplate="%s | MyAwesomeWebsite.com"
176 >
177 <title>Nested Title</title>
178 </Helmet>
179
180 outputs:
181
182 <head>
183 <title>Nested Title | MyAwesomeWebsite.com</title>
184 </head>
185 */}
186 titleTemplate="MySite.com - %s"
187
188 {/*
189 (optional) used as a fallback when a template exists but a title is not defined
190
191 <Helmet
192 defaultTitle="My Site"
193 titleTemplate="My Site - %s"
194 />
195
196 outputs:
197
198 <head>
199 <title>My Site</title>
200 </head>
201 */}
202 defaultTitle="My Default Title"
203
204 {/* (optional) callback that tracks DOM changes */}
205 onChangeClientState={(newState, addedTags, removedTags) => console.log(newState, addedTags, removedTags)}
206>
207 {/* html attributes */}
208 <html lang="en" amp />
209
210 {/* body attributes */}
211 <body className="root" />
212
213 {/* title attributes and value */}
214 <title itemProp="name" lang="en">My Plain Title or {`dynamic`} title</title>
215
216 {/* base element */}
217 <base target="_blank" href="http://mysite.com/" />
218
219 {/* multiple meta elements */}
220 <meta name="description" content="Helmet application" />
221 <meta property="og:type" content="article" />
222
223 {/* multiple link elements */}
224 <link rel="canonical" href="http://mysite.com/example" />
225 <link rel="apple-touch-icon" href="http://mysite.com/img/apple-touch-icon-57x57.png" />
226 <link rel="apple-touch-icon" sizes="72x72" href="http://mysite.com/img/apple-touch-icon-72x72.png" />
227 {locales.map((locale) => {
228 <link rel="alternate" href="http://example.com/{locale}" hrefLang={locale} key={locale}/>
229 })}
230
231 {/* multiple script elements */}
232 <script src="http://include.com/pathtojs.js" type="text/javascript" />
233
234 {/* inline script elements */}
235 <script type="application/ld+json">{`
236 {
237 "@context": "http://schema.org"
238 }
239 `}</script>
240
241 {/* noscript elements */}
242 <noscript>{`
243 <link rel="stylesheet" type="text/css" href="foo.css" />
244 `}</noscript>
245
246 {/* inline style elements */}
247 <style type="text/css">{`
248 body {
249 background-color: blue;
250 }
251
252 p {
253 font-size: 12px;
254 }
255 `}</style>
256</Helmet>
257```
258
259## Contributing to this project
260Please take a moment to review the [guidelines for contributing](CONTRIBUTING.md).
261
262* [Pull requests](CONTRIBUTING.md#pull-requests)
263* [Development Process](CONTRIBUTING.md#development)
264
265## License
266
267MIT
268
269<img align="left" height="200" src="http://static.nfl.com/static/content/public/static/img/logos/ENG_SigilLockup_4C_POS_RGB.png" />