Awesome
Preact Helmet
A document head manager for Preact
<img align="right" height="200" src="https://raw.githubusercontent.com/download/preact-helmet/master/logo.png" />This project is a port of react-helmet to Preact, the 3kB lightweight React alternative.
This Preact component will manage all of your changes to the document head with support for document title, meta, link, style, script, noscript, and base tags.
Inspired by:
- react-document-title
- react-side-effect
- preact-side-effect (port)
- react-helmet (obviously)
Table of Contents generated with DocToc
- Examples
- Features
- Installation
- Server Usage
- Use Cases
- Contributing to this project
- License
- More Examples
Examples
import {h} from "preact"; /** @jsx h */
import Helmet from "preact-helmet";
export default function Application () {
return (
<div className="application">
<Helmet title="My Title" />
...
</div>
);
};
import {h} from "preact"; /** @jsx h */
import Helmet from "preact-helmet";
export default function Application () {
return (
<div className="application">
<Helmet
htmlAttributes={{lang: "en", amp: undefined}} // amp takes no value
title="My Title"
titleTemplate="MySite.com - %s"
defaultTitle="My Default Title"
titleAttributes={{itemprop: "name", lang: "en"}}
base={{target: "_blank", href: "http://mysite.com/"}}
meta={[
{name: "description", content: "Helmet application"},
{property: "og:type", content: "article"}
]}
link={[
{rel: "canonical", href: "http://mysite.com/example"},
{rel: "apple-touch-icon", href: "http://mysite.com/img/apple-touch-icon-57x57.png"},
{rel: "apple-touch-icon", sizes: "72x72", href: "http://mysite.com/img/apple-touch-icon-72x72.png"}
]}
script={[
{src: "http://include.com/pathtojs.js", type: "text/javascript"},
{type: "application/ld+json", innerHTML: `{ "@context": "http://schema.org" }`}
]}
noscript={[
{innerHTML: `<link rel="stylesheet" type="text/css" href="foo.css" />`}
]}
style={[
{type: "text/css", cssText: "body {background-color: blue;} p {font-size: 12px;}"}
]}
onChangeClientState={(newState) => console.log(newState)}
/>
...
</div>
);
};
Features
- Supports
title
,base
,meta
,link
,script
,noscript
, andstyle
tags. - Attributes for
html
andtitle
tags. - Supports isomorphic/universal environment.
- Nested components override duplicate head changes.
- Duplicate head changes preserved when specified in same component (support for tags like "apple-touch-icon").
- Callback for tracking DOM changes.
Installation
npm install --save preact-helmet
Server Usage
To use on the server, call rewind()
after using render
from preact-render-to-string
to get the head data for use in your prerender.
Because this component keeps track of mounted instances, you have to make sure to call rewind
on server, or you'll get a memory leak.
import { render } from 'preact-render-to-string'
import Helmet from 'preact-helmet'
const markup = renderToString(<MyApp />);
const head = Helmet.rewind();
// populate some document template using `markup` and `head`
const html = `
<!doctype html>
<html>
<head>
${head.title.toString()}
${head.meta.toString()}
${head.link.toString()}
</head>
<body>
<div id="content">
${markup}
</div>
</body>
</html>
`;
head
contains the following properties:
htmlAttributes
title
base
meta
link
script
noscript
style
Each property contains toComponent()
and toString()
methods. Use whichever is appropriate
for your environment. For htmlAttributes, use the JSX spread operator on the object returned
by toComponent()
. E.g:
As string output
const html = `
<!doctype html>
<html ${head.htmlAttributes.toString()}>
<head>
${head.title.toString()}
${head.meta.toString()}
${head.link.toString()}
</head>
<body>
<div id="content">
${markup}
</div>
</body>
</html>
`;
As Preact components
If you are doing server side rendering with Preact, it may be easier to render the document template with Preact as well:
function HTML({head}) {
const attrs = head.htmlAttributes.toComponent();
return (
<html {...attrs}>
<head>
{head.title.toComponent()}
{head.meta.toComponent()}
{head.link.toComponent()}
</head>
<body>
<div id="content">
<MyApp />
</div>
</body>
</html>
);
}
Use Cases
- Nested or latter components will override duplicate changes.
<Helmet
title="My Title"
meta={[
{"name": "description", "content": "Helmet application"}
]}
/>
<Helmet
title="Nested Title"
meta={[
{"name": "description", "content": "Nested component"}
]}
/>
Yields:
<head>
<title>Nested Title</title>
<meta name="description" content="Nested component">
</head>
- Use a titleTemplate to format title text in your page title
<Helmet
title="My Title"
titleTemplate="%s | MyAwesomeWebsite.com"
/>
<Helmet
title="Nested Title"
/>
Yields:
<head>
<title>Nested Title | MyAwesomeWebsite.com</title>
</head>
- Duplicate
meta
and/orlink
tags in the same component are preserved
<Helmet
link={[
{"rel": "apple-touch-icon", "href": "http://mysite.com/img/apple-touch-icon-57x57.png"},
{"rel": "apple-touch-icon", "sizes": "72x72", "href": "http://mysite.com/img/apple-touch-icon-72x72.png"}
]}
/>
Yields:
<head>
<link rel="apple-touch-icon" href="http://mysite.com/img/apple-touch-icon-57x57.png">
<link rel="apple-touch-icon" sizes="72x72" href="http://mysite.com/img/apple-touch-icon-72x72.png">
</head>
- Duplicate tags can still be overwritten
<Helmet
link={[
{"rel": "apple-touch-icon", "href": "http://mysite.com/img/apple-touch-icon-57x57.png"},
{"rel": "apple-touch-icon", "sizes": "72x72", "href": "http://mysite.com/img/apple-touch-icon-72x72.png"}
]}
/>
<Helmet
link={[
{"rel": "apple-touch-icon", "href": "http://mysite.com/img/apple-touch-icon-180x180.png"}
]}
/>
Yields:
<head>
<link rel="apple-touch-icon" href="http://mysite.com/img/apple-touch-icon-180x180.png">
</head>
- Only one base tag is allowed
<Helmet
base={{"href": "http://mysite.com/"}}
/>
<Helmet
base={{"href": "http://mysite.com/blog"}}
/>
Yields:
<head>
<base href="http://mysite.com/blog">
</head>
- defaultTitle will be used as a fallback when the template does not want to be used in the current Helmet
<Helmet
defaultTitle="My Site"
titleTemplate="My Site - %s"
/>
Yields:
<head>
<title>My Site</title>
</head>
But a child route with a title will use the titleTemplate, giving users a way to declare a titleTemplate for their app, but not have it apply to the root.
<Helmet
defaultTitle="My Site"
titleTemplate="My Site - %s"
/>
<Helmet
title="Nested Title"
/>
Yields:
<head>
<title>My Site - Nested Title</title>
</head>
And other child route components without a Helmet will inherit the defaultTitle.
- Usage with
<script>
tags:
<Helmet
script={[{
"type": "application/ld+json",
"innerHTML": `{
"@context": "http://schema.org",
"@type": "NewsArticle"
}`
}]}
/>
Yields:
<head>
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "NewsArticle"
}
</script>
</head>
- Usage with
<style>
tags:
<Helmet
style={[{
"cssText": `
body {
background-color: green;
}
`
}]}
/>
Yields:
<head>
<style>
body {
background-color: green;
}
</style>
</head>
Contributing to this project
Please take a moment to review the guidelines for contributing.
License
MIT
More Examples
react-helmet-example (for React, but still useful)